Elements of Scalable Web Development

Specification 00

Common contract
Status
Canonical brief
Application
Work Activity Tracker

Behavior, technical freedom, evidence, and shared evaluation.

Common Project Specification#

Work Activity Tracker#

This specification defines the application that your group will implement three times during the course. The required behavior remains substantially the same. The development setup changes:

  1. Establish: large model and a single-agent workflow.
  2. Challenge: small model and a single-agent workflow.
  3. Compare: an agent fleet with a declared model configuration.

Each phase produces a separate implementation. The purpose is not to find one universally best model, framework, or architecture. The purpose is to compare how different development systems approach the same bounded web application and to reason about the scalability of both the application and the development process.

The phase specifications define additional constraints and deliverables. This common specification applies to all three phases. Read the project introduction before starting work; it explains submission checkpoints, evidence records, external contributions, and learning expectations.

Shared engineering sessions#

Each group must hold one shared engineering session of approximately 30 minutes per phase, within its existing project work. Use three responsibilities: operator works with the agent and explains the request; challenger questions assumptions and proposes alternatives; validator inspects the implementation, runs checks, and explains the acceptance decision. Rotate these responsibilities across phases so each student practices all three. For an approved pair, combine challenger and validator and rotate the operator; for a larger group, divide active investigation and validation tasks so everyone contributes.

Use this sequence:

  1. Before consulting the agent, each student briefly predicts the behavior or proposes a design.
  2. Compare predictions, agree on the question, and investigate the implementation with the agent.
  3. Run a relevant check and have someone other than the operator explain whether to accept, revise, or reject the result and what remains uncertain.

Use a question tied to the current phase:

  • Establish: Does a work-item transition reliably produce the corresponding activity event?
  • Challenge: What happens when two clients attempt the same transition concurrently?
  • Compare: Does a proposed scaling response improve the measured limit, and what new failure can it introduce?

An equivalent question is acceptable when it examines the same phase's correctness, pressure, or scaling reasoning. Record participants and responsibilities, the initial disagreement or prediction, the check and result, and the acceptance decision compactly in the existing decision record or AI-use log. Link the relevant code or evidence; do not submit another report or a raw chat transcript. This session replaces part of ordinary project discussion and reflection within the published time budget. Shared work may be remote and does not require a shared personal account.

Solo engineering session#

For an approved solo allocation, keep one approximately 30-minute engineering session per phase within ordinary project work. Before agent use, write your prediction and the acceptance check. Then act as operator to investigate, as challenger to consider a competing explanation or design and a concrete failure case, and as validator to run checks and explain acceptance or rejection. Keep the phase questions above and link the compact record from existing evidence. Arrange a short instructor discussion per phase: explain the decision and result, answer an independent challenge, and record what changed or remains uncertain. The discussion may be remote; agree its time budget in advance and record it in the existing evidence rather than adding a report. The instructor records completed discussion evidence in the workspace.

1. Application Brief#

Build a web application that records activity around work items.

The application contains:

  • Workspaces, which separate independent groups or projects.
  • Work items, which belong to a workspace and move through a small lifecycle.
  • Activity events, which record what happened to a work item.

The domain is intentionally familiar and compact. Your group may give the application a visual theme or adapt the terminology—for example, a workspace may be presented as a classroom, game, laboratory, production line, or agent workflow. The required capabilities must remain identifiable to an auditor, but the specification does not prescribe one ideal interpretation or design.

This specification primarily describes observable behavior. When several interpretations satisfy the requirements, choose one, implement it consistently, and document any assumption that affects how the application is used or evaluated. You do not need to make the implementation unusual deliberately; differences are expected to emerge from ordinary design and development decisions.

Compare requires analysis of the actual fleet execution record. As an optional extension, apply the same domain model to that record: a fleet run can become a workspace, delegated tasks can become work items, and agent or human actions can become activity events. Importing or displaying fleet traces is not part of the required application behavior in any phase.

2. Required Domain Model#

Your implementation must represent the following concepts. Field names and internal representations may differ.

2.1 Workspace#

A workspace must have:

  • a unique identifier;
  • a name.

2.2 Work item#

A work item must have:

  • a unique identifier;
  • a workspace;
  • a title;
  • a state in a lifecycle with at least three ordered stages corresponding to:
    • not started, such as open;
    • active, such as in_progress;
    • finished, such as done.

You may add descriptions, owners, labels, priorities, deadlines, or other fields.

2.3 Activity event#

An activity event must have:

  • a unique identifier;
  • an event type;
  • the workspace concerned;
  • the work item concerned;
  • an occurrence timestamp;
  • an actor represented at least by a name or identifier.

The required event meanings are:

  • creation of a work item, such as item_created;
  • movement into the active stage, such as work_started;
  • movement into the finished stage, such as work_completed.

Events may contain additional metadata. Names and representations may differ if their mapping to the required meanings is documented.

3. Required Behavior#

3.1 Workspace management#

A user must be able to:

  • create a workspace;
  • view the workspaces needed to use the rest of the application.

Editing and deleting workspaces are optional.

3.2 Work-item lifecycle#

A user must be able to:

  • create a work item in a workspace;
  • move a work item from the initial stage to the active stage;
  • move a work item from the active stage to the finished stage;
  • see the current state of a work item.

Creating a work item must record one creation event. Each successful state transition must record the corresponding activity event.

Unsupported transitions must be rejected. For example, an item cannot skip directly from the initial stage to the finished stage. A rejected transition must not change the item state or record a successful transition event.

3.3 Activity feed#

A user must be able to:

  • view recorded events;
  • identify the event type, workspace, work item, actor, and occurrence time;
  • filter events by workspace;
  • filter events by event type.

The default ordering must be documented and deterministic. Newest-first ordering is recommended.

3.4 Summary#

The application must show at least one derived summary for a selected workspace:

  • the number of work items in each state; or
  • the number of events of each type.

The summary may be calculated when requested, maintained incrementally, or produced in another explainable way.

3.5 Validation and errors#

The application must:

  • reject missing or invalid required values;
  • preserve a valid state when an operation fails;
  • show the user an understandable error;
  • avoid exposing secrets or a raw internal stack trace through the user interface.

3.6 Persistence#

Workspaces, work items, their states, and activity events must survive an ordinary application restart.

The storage mechanism is your choice.

3.7 Intentionally unspecified details#

The specification does not prescribe:

  • page structure, navigation, or visual design;
  • whether interactions use forms, links, buttons, an API, or another interface;
  • exact URLs, endpoint shapes, or transport formats;
  • whether rendering happens on the server, client, or both;
  • identifier format or timestamp precision;
  • how actors are chosen or represented beyond the required event information;
  • how state and events are represented or stored internally;
  • how the summary is calculated;
  • module, service, or deployment boundaries;
  • behavior outside the required lifecycle and acceptance scenarios.

Resolve these details in a coherent way. Record assumptions that another group would need in order to use, test, or understand the result.

4. Common Acceptance Scenarios#

Another group and the instructors must be able to verify at least the following scenarios through the running application:

  1. Create two workspaces.
  2. Create work items in both workspaces.
  3. Confirm that each new work item begins in the documented initial state.
  4. Start one work item and confirm that it enters the documented active state.
  5. Complete that item and confirm that it enters the documented finished state.
  6. Attempt an unsupported state transition and confirm that it is rejected without changing the stored state.
  7. View the activity feed and find one event for each successful operation.
  8. Filter the feed to one workspace and confirm that events from the other workspace are absent.
  9. Filter the feed by event type.
  10. View the required summary and verify it against the created data.
  11. Restart the application and confirm that the data remains available.
  12. Submit invalid input and confirm that the result is understandable and does not corrupt existing data.

The course may provide automated checks for behavior that can be tested without prescribing a particular implementation. Passing an automated check does not replace human review.

5. Technical Freedom and Experimentation#

You may choose:

  • the programming language;
  • the web framework or combination of frameworks;
  • server-rendered pages, a client application, LiveView-style interaction, or another web approach;
  • a monolith, client-server design, serverless design, or another explainable architecture;
  • relational, document, file-based, event-oriented, in-memory-with-persistence, or other storage;
  • local, containerized, cloud, edge, or other deployment;
  • testing, observability, and build tools.

Next.js, Elixir, Python, and less common stacks are all valid choices. A familiar stack is not automatically safer, and an exotic stack is not automatically more innovative. Evaluation is based on what the choice enables, what it costs, how well the result satisfies the contract, and whether another group can understand and run it.

For the clearest within-group comparison, you should normally keep the same primary language and framework family across all three implementations. Different groups are encouraged to choose different stacks. A group may change its own stack between phases when it has a clear experimental reason and instructor approval, but the final analysis must then treat the stack change as a confounding factor.

Experimentation is encouraged when it serves a question the group can explain. Examples include:

  • comparing server rendering with a client-heavy approach;
  • using an actor model or functional language;
  • trying an event-sourced representation;
  • using an embedded or unusual database;
  • targeting an edge or serverless runtime;
  • minimizing client JavaScript;
  • optimizing for local-first operation, privacy, portability, or resource efficiency.

Your group owns the operational consequences of its choices. A stack that nobody outside the group can install, run, test, or inspect has not met the project requirements, even if the application worked on the authors' machine.

No particular stack receives extra credit merely for being fashionable, complex, or unusual.

6. Minimum Project Harness#

Project harness is the course's label for the repository guidance, reproducible setup, and executable checks that support its development workflow. Each implementation must provide:

  • a README.md that explains the application, prerequisites, setup, running, testing, and the chosen stack;
  • one supported path from a clean checkout to a running application;
  • pinned or otherwise reproducible dependency and runtime versions;
  • an example configuration file when configuration is required;
  • no committed secrets;
  • a repeatable way to create enough demonstration data for the acceptance scenarios;
  • a repeatable workload adapter for the shared runtime protocol;
  • at least one automated validation command;
  • tests covering the work-item lifecycle and its event recording;
  • project instructions for the AI development workflow;
  • an architecture or data-flow diagram and a short architecture note for the core event workflow;
  • maintained specifications for the core event workflow and consequential project work, including intended behavior and acceptance conditions;
  • an evolving decision log, using ADRs or an equivalent approach, beginning with the stack choice.

Maintained specifications and decision records#

Choose and improve how you maintain specifications across the projects. Documents, structured issues, examples or executable scenarios are suitable when intended behavior, acceptance, constraints, assumptions and scope are clear and discoverable by humans and agents. Refer to the common course contract rather than reproduce it; your project context cannot waive its requirements. Use this context when briefing agents, dividing work and accepting results, and update it as legitimate clarifications and agreed changes occur. Distinguish intended behavior, implemented behavior and known gaps; a defect alone does not justify changing the specification to match it.

Record consequential decisions while working: context, alternatives, decision and rationale, assumptions and consequences, status and owner, evidence, reversibility and a condition for revisiting the choice. Start in A, revisit relevant choices in B, and use the accumulated reasoning for C's fleet, scaling and final decisions. Explain why a choice is retained, revised or rejected; an unchanged decision can be well supported. Preserve earlier records and link replacements when superseded, with implementation status and evidence scoped to the applicable phase and revision. The specification describes current intent; the log preserves reasoning and history, and the architecture note explains the running system. They may share a tool or document when their roles remain clear. No particular tool, file layout, word count or record quota is required. Link readable phase snapshots or exports from the evidence index so the reviewer does not need access to your chosen tool. Use the existing representative agent-task record to show how this context informed work and validation.

Ownership card#

Include a short Ownership card under that heading in each phase's evidence index, identifying the phase and submitted revision for the core event workflow. Use brief answers or evidence links for these six fields:

Field What to record
Code entry points Source root and composition or request entry point for the workflow.
State authority Authoritative state and the component responsible for changing it.
Public contracts Interfaces, lifecycle and event-recording obligations.
Dependency direction Which components may depend on which others.
Excluded responsibilities Responsibilities outside this workflow or component.
Validation and acceptance Relevant checks and results, plus the role responsible for accepting the work.

Keep the card consistent with the current specification, architecture and decision records. It locates evidence for existing architecture and ownership criteria; a completed card alone does not establish correctness or earn separate points.

Setup may use native tools, containers, a development environment definition, or another documented mechanism. Do not require an auditor to infer missing steps from knowledge held only by your team.

The README must distinguish mandatory prerequisites from optional development conveniences. If the stack requires unusual system dependencies or hardware, document them near the beginning.

7. Shared Runtime Workload and Progressive Scalability Analysis#

You do not have to build a production-scale distributed system. You must be able to measure a stable baseline and reason about what your implementation would do under pressure.

7.1 Shared baseline workload#

You may use the course-provided benchmark runner or implement your own under this same protocol. Both paths require the same fixture, operation mix, seeded order, boundaries, profiles, repetitions, resets, deadlines, outcome accounting and correctness checks. The runner owns generic scheduling, timing and reporting; the application adapter must exercise the real application and persistence path. Writing a custom runner earns no separate points; its compliance, results and reproducibility must be inspectable.

Run the same stack-neutral workload against implementations A, B, and C. The workload measures logical user operations from the adapter's request until the application returns an observable result, not individual internal network requests. The adapter may drive the user interface, a documented application interface, or another repeatable boundary that exercises the real application and persistence path. Choose that boundary before measuring A and keep it across B and C: API-response latency and browser-visible completion are different outcomes. Define the start and completion events, including response validation and what constitutes acknowledged persistence; separate additional diagnostic boundaries rather than ranking them together.

Start each measured profile from this fixture:

  • eight workspaces named workspace-01 through workspace-08;
  • fifty work items per workspace: twenty in the initial state, fifteen in the active state, and fifteen in the finished state;
  • all activity events implied by creating and transitioning those items;
  • four actors named actor-01 through actor-04, distributed deterministically across the fixture;
  • stable fixture keys that the adapter can map to implementation-specific identifiers.

A workload cycle uses this operation mix:

Share Logical operation Target rule
30% Read the activity feed Divide evenly between the unfiltered feed, one workspace, and one event type
15% Read a workspace summary Rotate evenly through the eight workspaces
20% Create a work item Rotate workspaces and actors; use a unique deterministic title
15% Move an existing initial item to the active state Use a distinct valid target for each operation
10% Move an existing active item to the finished state Use a distinct valid target for each operation
10% Attempt an unsupported transition Treat the documented rejection as an expected result, then verify that state and events did not change

Use a fixed operation-order seed and record it. Concurrent operations in this baseline should use distinct work items; contention on the same item belongs in a pressure scenario.

Run the following profiles:

Profile Operations Concurrency Repetitions Reset rule
Warm-up 100 1 1 unmeasured Reset and reseed afterward
Steady 500 4 3 measured Reset and reseed before each repetition
Higher concurrency 200 16 3 measured Reset and reseed before each repetition

These are closed-loop profiles: each of the declared workers dispatches its next logical operation only after its previous operation completes or times out, with no intentional think time. Workers take operations from the fixed seeded sequence until it is exhausted; concurrency is a maximum, not a guaranteed arrival rate. Disable adapter retries for the baseline, and record any application-level retry policy and internal attempts separately from logical operations. Record the cache policy too: resetting the fixture after warm-up does not guarantee warm data caches.

Predeclare one per-operation timeout and one overall run deadline, held constant across comparable runs. Use 10 seconds per operation and five minutes per measured repetition unless the instructor approves different limits for the chosen boundary before the comparison. At the run deadline, stop dispatching, record queued operations as not started and active operations as unfinished, and preserve their identifiers for reconciliation. A timeout is an observed deadline crossing, not an exact completion latency or proof that a write did not commit. After the run, reconcile state and events for timed-out or unfinished writes, and report unresolved outcomes explicitly. Quiesce or isolate outstanding work before resetting the fixture so a late write cannot contaminate the next repetition.

For every measured repetition, record:

  • implementation identifier, commit, environment, configuration, adapter version, and operation-order seed;
  • elapsed time, scheduled and dispatched counts, completed valid operations, and valid completions per second;
  • median and 95th-percentile latency for completed valid operations, clearly labeled as conditional on completion, plus their sample counts and the percentile calculation;
  • separate counts for not-started, unfinished, and timed-out operations, including their known waiting durations or deadline lower bounds;
  • expected rejections separately from timeouts, crashes, invalid responses, and other unexpected errors;
  • post-run checks for state, event, filter, and summary correctness;
  • one resource-efficiency proxy that can be collected consistently across phases, such as peak memory, CPU time, database growth, or billed execution time.

Report each repetition and the median result rather than presenting only the best run. Expected unsupported-transition rejections count as valid completed operations only when the unchanged-state check passes; unexpected admission rejections do not. Show read, write, and expected-rejection counts separately so fast refusals cannot conceal lost useful work. For the baseline p95, use the nearest-rank observation at ceil(0.95 × n) in the sorted valid latencies, and retain the raw observations. In 200 observations, only about ten lie in the upper 5%; per-operation subsets are smaller still. These short runs expose variation and regressions, but cannot establish stable production tail latency; report small subsets descriptively and avoid spurious decimal precision. Absolute results from different hardware or hosted environments should not be ranked as though the environment were controlled. If a platform limit prevents a profile from completing, preserve that result as evidence and label any reduced diagnostic run instead of silently changing the protocol.

The baseline is an experimental reference, not a claim that this operation mix represents every real workload.

7.2 Progressive pressure analysis#

Use the baseline workload as the starting point for the cumulative pressure analysis. Change one main condition at a time where practical so the effect remains interpretable—for example concurrency, fixture size, dependency latency, or repeated requests.

Use these scenarios as a shared pressure catalog:

  • many independent workspaces;
  • concurrent users changing different and identical work items;
  • high and bursty event volume;
  • storage growth over time;
  • slow or temporarily unavailable dependencies;
  • retries that may repeat a request;
  • automated reads or writes whose application value, resource cost, or access pattern differs from ordinary interactive use;
  • demand for recent activity and historical summaries;
  • a need to retain, aggregate, archive, or delete old events.

Do not exhaustively apply the entire catalog after every phase. In Establish, select one primary pressure that is likely to expose an important architectural limit and define it as a documented transformation of the baseline workload. Reuse that scenario and its procedure in Challenge and Compare so the three implementations remain comparable. Challenge repeats the primary pressure and adds one bounded correctness or recovery investigation, such as concurrent work-item transitions, reusing the engineering session and its evidence where appropriate. Compare repeats the primary pressure on C, implements one justified scaling response in A, B or C, measures before and after, and checks a new failure or recovery obligation introduced by the response. Application and workflow formal-model reasoning, realistic deployment and the deployed baseline rerun remain required. Further pressure scenarios are optional explorations within the existing phase budget. The required investigation supports full credit, including grade 5; extra scenarios have no separate point allocation and cannot replace required evidence. Optional scope does not weaken the evidence needed for a chosen claim, including the conditional arrival-controlled procedure below.

The shared baseline supports comparison across groups; chosen primary pressures and extensions may differ. Identify required and optional findings in the final matrix with their environments, scope and conditions visible. Uncontrolled differences do not establish model effects, and raw latency alone does not rank the quality of a group's work.

When automated use or data exposure is the selected pressure, also distinguish cooperating, authorized, and abusive consumers; state which information is intentionally public or retained; and account for the false-positive and accessibility cost of the proposed control.

Use runtime evidence where the available workload and environment allow it. Label reasoned projections as projections rather than observations. The goal is a cumulative, justified analysis, not repeated hypothetical matrices or distributed infrastructure added without evidence.

Pressure-record template#

Use this record in your existing evidence index for each pressure analyzed in depth. It also supplies the fields for Establish’s two bounded claims; a contributor/change claim may use a scenario rather than a runtime workload. Keep the same record across phases, adding revision-specific evidence rather than copying the analysis into new reports.

### Claim or pressure: <name>

- Goal and pressure: <what must remain true; what increases or changes>
- Range or scenario: <conditions studied>
- Boundary and constraints: <system boundary; fixed assumptions and limits>
- Procedure: <baseline transformation or change scenario; how to repeat it>
- First limit: <what fails or slows first; resource, quota, or dependency>
- First useful signal: <what would reveal the problem>
- Candidate response and trade-off: <action; new cost or failure mode>
- Prepared recovery: <action available if the limit is reached>
- Evidence: <implementation/revision; result and evidence link; measured or projected>
- Excluded dimension: <one aspect this claim does not cover>

Keep every measured repetition and the required measurement metadata in the linked evidence; the record summarizes them. For Establish’s contributor/change claim, a runtime procedure or prepared recovery action may be inapplicable; state why.

7.3 Arrival-controlled overload and recovery#

When applicable: this run is required only for a selected pressure or claim about sustained incoming demand, queue growth, or admission control.

Add a bounded open-loop pressure run within that experiment. It replaces part of the existing pressure analysis rather than adding another mandatory scenario for every build. Schedule arrivals independently of earlier completions; a closed-loop client population can reduce its own offered load as the application slows.

Use a pilot to select and then freeze three arrival rates expected to be below, near, and above the observed service limit, with 30 seconds at each rate followed by up to 60 seconds of drain and recovery observation. Declare the operation mix, fixture, timing boundary, request timeout, maximum in-flight work, and total attempt budget before the comparison, and keep them stable when rerunning the selected pressure. Do not silently lower an assigned rate when the generator or application cannot keep up. If a generator cap prevents dispatch, count the scheduled operation as not dispatched; do not accumulate an unbounded catch-up queue.

Record scheduled arrivals, actual dispatch times and scheduling lag, application admissions where observable, expected domain rejections, overload rejections, valid completions, timeouts, and unfinished work separately. If admission is not observable, label it unknown rather than inferring it from dispatch. Report both scheduled-arrival-to-result time, which includes generator waiting, and dispatch-to-result time, with the same outcome and censoring rules as the baseline. Record queue length or age and resource use during load and drain where observable; distinguish application backlog from generator lag. At the drain deadline, retain unfinished identifiers, check for late writes or duplicates, and verify ordinary service has recovered. If it has not, report that result and perform the prepared recovery action.

8. Permitted Transfer Between Implementations#

Implementations must begin in separate repositories or clean implementation directories.

You may carry forward:

  • this specification and instructor-provided materials;
  • acceptance scenarios and course-provided tests;
  • your own written lessons, behavior-level specifications, decision history and comparison notes, revisited for each fresh implementation;
  • domain terminology and user-facing copy;
  • technology-neutral diagrams;
  • generic personal or course tooling that does not contain application behavior.

You may not carry forward:

  • application source code;
  • implementation-specific tests;
  • generated components or configuration copied from an earlier implementation;
  • an earlier repository used as the starting point for the next phase;
  • prompts that contain substantial blocks of the earlier implementation.

The optional bounded paired task is an explicit exception for experimental copies of a frozen revision, not for implementation C's starting code. Transferred reasoning does not establish that a choice is implemented or validated in the next build; implementation-specific bindings, tests and configuration remain subject to the restrictions above.

When uncertain, disclose the reuse in the evidence package. The purpose of the rule is to create genuinely fresh implementations, not to prevent students from learning.

The same restriction applies to other groups' submissions. Learn from their evidence and engineering decisions, but do not copy their application source, implementation-specific tests, or implementation-specific configuration into your own build. Acknowledge ideas that materially inform your decisions.

Third-party libraries, public starter templates, framework generators, and generic personal scaffolds are allowed if their use is documented and permitted by the course's normal rules.

9. Common Submission Bundle and Comparable Evidence#

After every phase, submit one common bundle containing:

  • that phase's implementation in its own repository or clean implementation directory;
  • the comparable evidence categories in sections 9.1–9.4;
  • the bounded cross-team audit report and a short response from the authors; and
  • the additions named by the phase specification.

A listed requirement does not automatically require a separate file. One clearly structured artifact may satisfy several fields, and the phase specifications name only additions to this common bundle. Use the same evidence categories after every phase so later comparisons can refer to the earlier package rather than reconstruct it.

Submit the frozen implementation and initial evidence first, then attach the audit report and authors' response to the same record at the evidence deadline. The project introduction defines these stages and class access. Identify the group and phase in the evidence index, link the submitted revision and each required artifact, and keep private individual portfolios outside the technical bundle.

9.1 Development setup#

Identify the implementation and submitted commit, language, framework, storage and deployment approach. Link the exact version or retained snapshot of the published course configuration and confirm the models, role or size assignments, actual inference routes and local or hosted environment used. Record deviations, including substitutions, fallback and changes during an attempt; the configured route alone is not proof of the route that ran.

The referenced configuration and deviations together must identify the agent tool/version, material imported instructions or capabilities, orchestration, relevant hardware or hosted resources, data paths and fallback policy. You may reference unchanged published details instead of restating them. When exposed and material to a claim, add resolved revisions or digests, quantization, runtime, context, resource limits, accelerator residency or offload, and imported-capability versions. Mark unavailable details honestly; do not reconstruct hidden settings or treat an unavailable field as confirmation of the published default.

9.2 Effort and execution#

  • elapsed project time;
  • estimated active human time;
  • approximate model usage across all workers and attempts, cost under a declared pricing or departmental resource-cost basis, or measurable resource use;
  • failed or abandoned attempts worth noting;
  • important human interventions and corrections.
  • one representative AI-assisted task record containing the task brief, relevant model and agent configuration, checks, trace or compact execution evidence, human correction, acceptance decision, and known limits.

Exact accounting is not expected when a tool does not expose it. State what could and could not be measured. Department-provided access may remove student spending while still consuming inference resources; report the cost basis separately from the student's payment.

9.3 Product evidence#

  • acceptance-scenario results;
  • automated test results;
  • results from the repeated shared baseline workload, including the declared resource-efficiency proxy;
  • known defects or incomplete requirements;
  • deployment URL, local run evidence, or another agreed operational artifact.

Use the same resource-efficiency signal and procedure across phases where practical. If direct energy measurement is unavailable, report an observable resource proxy and do not relabel it as energy or carbon.

Every implementation must have a reproducible operational path. The Compare phase adds one realistic deployment outside the author's development process; its specification defines that final requirement.

9.4 Engineering explanation#

  • architecture and data-flow diagram;
  • evolving decision log and readable maintained-specification snapshot, linked through the ownership card;
  • the phase's cumulative scalability-pressure record;
  • one concrete development bottleneck supported by observations, with a checked improvement or a justified follow-up decision;
  • short reflection distinguishing observation from a possible explanation.

For the friction entry, identify phase and revision, bottleneck and supporting evidence, response and rationale, and check result or justified next step. Reuse task, audit and validation evidence in the index; no additional report is needed. Setup, comprehension, change, testing, review, deployment, operations and coordination are prompts, without compulsory commentary on every category. One well-supported finding and response can satisfy the friction requirement for full credit. Keep an unchanged or worse check result visible, and distinguish a proposed follow-up from an improvement already achieved. Both incoming and outgoing audits remain required under section 10, with their actual outcomes, setup/probe boundaries and reporting conditions preserved.

Do not submit an uncurated raw agent transcript as the main evidence. Preserve enough task, prompt, trace, and review information to explain consequential decisions and failures.

9.5 Package the source#

Submit the smallest complete source bundle that another group can reproduce without your personal repository credentials. Include application source, relevant tests, small synthetic fixtures, dependency manifests and lockfiles, migrations, setup scripts, example configuration and curated technical evidence. Exclude installed dependencies such as node_modules and .venv, .git, caches, reproducible build output, model weights, secrets and personal data. If a vendored dependency or generated artifact is necessary to run the supported path, include it and explain the exception; this is not a source-file-only restriction.

Write instructions for unpacking the archive, installing the declared dependencies, initializing fixtures, running the application and executing validation. Retain the full implementation commit hash. The course workspace records the archive's size and SHA-256 digest and retains that copy; a repository URL is optional context. An archive or hash alone does not prove it matches the declared commit or that the application works.

For a Git project, one starting point is:

git archive --format=zip --output=../source.zip <full-commit-hash>
unzip -l ../source.zip

This packages committed files only and does not include .git or untracked dependencies. It still includes unwanted files that were committed; review the contents and use versioned .gitattributes export-ignore rules for reproducible output or other exclusions where appropriate. Inspect configuration and evidence for secrets or personal data. Unpack into a clean directory and follow the documented setup and validation path before submission. For other archive tools, inspect their file listing and perform the same clean-directory check. The course server does not execute uploaded code or treat filenames as proof of safety or completeness.

Use the workspace's common and selected phase checklist to index evidence locations and declare missing or incomplete work. One artifact may satisfy several entries; checking an entry does not award points. Each run retains an archived requirement edition rather than silently following later edits to these briefs. Complete technical evidence and the author response in the later evidence stage; do not replace the original archive, setup or initial evidence. Compare links the existing A and B submission records instead of uploading their archives again.

10. Bounded Cross-Team Audit#

After each phase, another group will inspect the implementation for a limited period using only the repository and submitted instructions. Use the same audit tool policy in every phase and, where scheduling allows, the same auditing group. Record unavoidable changes in auditors or tools as comparison limitations.

The instructor assigns the auditing group and ensures it can read and check out the frozen implementation and access the submitted technical evidence. Use the link supplied with the audit assignment to locate that revision; work on a disposable checkout and record access problems and any prior inspection before attempting the probe. The course submission index opens for general class browsing after the audit window closes. Return the report to the authors and teaching staff, then link it from the authors' phase bundle together with their response. Auditors provide evidence for assessment; the instructor awards the project score. Your work on an assigned audit may also support your own individual contribution evidence.

The auditing group will:

  1. attempt the documented setup;
  2. run the documented validation command;
  3. check a sample of the common acceptance scenarios;
  4. locate where one important domain behavior is implemented;
  5. identify one hidden assumption, inconsistency, or comprehension problem;
  6. attempt the small change probe supplied for that phase;
  7. return a concise friction report.

Solo audit arrangements#

A solo student still needs independent review of each frozen implementation. The instructor assigns a human reviewer, who follows the same setup, validation and bounded change-probe protocol and returns a report tied to the frozen revision. The instructor records the reviewer, report and revision; the student responds in the existing technical evidence stage. Being the sole author does not make self-review independent evidence.

For the outgoing audit, assign another course group where possible. Otherwise supply a reproducible reference repository, full commit hash, supported setup/validation, a phase-specific change probe and the common audit tool policy. Use synthetic data and ensure the student has legitimate access without receiving another person's credentials or private records. Withhold the reference/probe until the audit window opens; retain the assignment after the student's implementation freezes. The reference must differ from the student's submitted implementation. Record prior exposure and distinguish a supplied reference from a contemporary class submission in comparisons. The student returns the same bounded friction report and indexes its useful review evidence in the private portfolio. Neither completing a reference audit nor receiving an instructor audit automatically awards points.

10.1 Change-probe protocol#

The change probe is this course's bounded task for maintainability assessment. It provides evidence about understanding, modifying, and validating one change under recorded conditions; it does not establish a complete maintainability score.

The instructor releases one phase-specific probe only after the implementation has been submitted. The probes use different product language but exercise an equivalent vertical slice and acceptance burden. The current phase-specific prompt, fields and values are withheld until release. Record exposure to prior phases or earlier published examples as a familiarity limitation rather than assuming the general probe pattern is unknown.

The change-probe portion of the audit lasts thirty minutes. Begin timing after the auditor receives the prompt and has a runnable checkout, so setup friction and change friction remain separate observations. During the time box:

  • use only the submitted repository, its instructions, and the common audit tool policy;
  • do not ask the authors where the change belongs;
  • work in a disposable branch or copy rather than modifying the submitted implementation;
  • run relevant existing checks before adding a focused automated test when time permits;
  • stop when the time expires, even if the change remains incomplete.

If the submitted setup cannot be made runnable during the audit, record the probe as not attempted because setup blocked it. An estimate may be included as commentary, but it does not count as completed change evidence.

10.2 Friction report#

Return any patch or diff with the following report in the existing audit submission. Use the same template for a group audit or an approved solo/reference audit; it does not add another submission.

### Friction audit: <group/reference, phase, frozen revision>

- Auditor and conditions: <auditor; tool policy; prior inspection or exposure>
- Setup: <outcome; setup time; access or setup problems>
- Locate the change: <time to identify UI, application, domain, persistence, and test locations>
- Probe: <complete / partial / blocked / not attempted; probe time, excluding setup>
- Acceptance checks: <completed; still missing>
- Changes: <files or boundaries; any duplicated change; patch/diff link>
- Validation: <commands and results; existing regressions>
- Assumptions and gaps: <documentation gaps; remaining uncertainty>
- First friction: <first point where progress slowed or stopped>

The audit is not a full code review and does not transfer ownership. Auditors are not expected to become experts in the chosen stack. Difficulty caused by an unfamiliar technology is useful evidence, but the report should distinguish ordinary learning from missing documentation or accidental complexity.

The authors may correct factual misunderstandings in the report, but they should not erase evidence that the system was difficult to understand.

11. Optional Extensions#

Complete the common requirements before adding extensions. Suitable extensions include:

  • authentication and roles;
  • work-item assignment;
  • comments or additional event types;
  • search, pagination, or richer filters;
  • import and export;
  • real-time updates;
  • offline behavior;
  • an API for external event producers;
  • accessibility improvements;
  • localization;
  • richer observability;
  • import and visualization of an agent-workflow trace;
  • explicit idempotency support;
  • retention, archival, or deletion policies;
  • performance or resource-efficiency improvements.

Optional scope must be reported separately so that a larger feature set is not mistaken for a better result.

12. Common Evaluation Principles#

Every phase is evaluated using these principles:

  • required behavior works;
  • the stack and architecture are understood and justified;
  • setup, testing, and operation are reproducible;
  • scalability claims are tied to evidence and explicit trade-offs;
  • AI-generated work is reviewed rather than accepted by default;
  • reporting is honest about failures, intervention, and uncertainty;
  • optional output volume does not substitute for the common core;
  • another group can inspect the project without relying on private explanations.

The phase specifications describe the emphasis and deliverables for each build.