Session M3-01 lab: Build and review a canvas contract¶

Duration: 2 hours
Difficulty: Advanced
Prerequisites: Sessions M1-01 to M1-03, M2-01 to M2-04 Deliverable: A tested canvas and its final state

Objective¶

Use one synthetic delivery-readiness contract from setup through handoff. Test the contract locally, then create the canvas in the Copilot app. Make visible and agent-requested changes to the same state. Check that an invalid change is rejected, then recover without changing the rule.

Deliverables¶

Submit:

your completed canvas-contract.md;
the generated extension location;
final state that matches the accepted transitions.

Access policy¶

The lab requires GitHub Copilot app access and the built-in /create-canvas skill. Project scope requires approval to create files under .github/extensions.

If app access or the skill is unavailable, stop the lab. If project scope is not available, use user scope. Do not install a replacement or copy the synthetic workflow into another external service.

Setup¶

From the repository root:

cd sessions/session-m3-01-copilot-app-canvases/lab/starter
npm test

Expected result:

tests 4
pass 4
fail 0

Open these files:

Copy the record files to a writable working folder if you do not want to edit the starter assets.

Time plan¶

Part	Work	Time
1	Check access and contract	20 min
2	Run the prepared contract tests	15 min
3	Create the canvas	25 min
4	Make two visible state changes	20 min
5	Check rejection and recovery	20 min
6	Inspect and hand off	20 min

Part 1: Check access and contract (20 minutes)¶

Select project or user scope.
Check that all data comes from prepared-items.json.
Review every state field, human action, agent capability, and validation rule in canvas-contract.md.
Replace the owner and reviewer placeholders.
Check the retirement trigger.

The contract must retain these rules:

statuses are planned, in-progress, review, and ready;
only one named item changes per update;
ready requires non-empty evidence;
unknown items and statuses are rejected;
no external system is connected.

Checkpoint 1: A peer can explain the contract without adding verbal requirements.

Part 2: Run the prepared contract tests (15 minutes)¶

Run:

npm test

Read test/canvas-contract.test.mjs and map each test to a contract rule.

Record:

the command;
pass or fail;
the four rules tested;
any mismatch between code and contract.

Do not continue with a failing harness. Fix only a mismatch caused by your edits, or reset your working copy from lab/starter/.

Checkpoint 2: Your local harness passes, and your group can identify the planned rejection.

Part 3: Create the canvas (25 minutes)¶

Open a GitHub Copilot app session with the required access. Run:

/create-canvas

Create a delivery-readiness canvas from @prepared-items.json.
Use the contract in @canvas-contract.md.
People can add evidence and update one item.
Copilot can read the board, update one named item, and list review flags.
Reject unknown items or statuses. Require evidence before ready.
Do not connect external systems.

Choose:

project scope only when .github/extensions is approved for the training repository;
user scope when a personal local extension is approved.

Inspect the generated directory, metadata, dependencies, state, visible controls, and agent-callable capabilities. Ask Copilot to remove anything outside the contract.

Checkpoint 3: The canvas shows all three prepared items and no extra capability.

Part 4: Make two visible state changes (20 minutes)¶

Use the same state for both paths.

Change A: direct human action¶

Move WEB-318 from review to ready.

This should succeed because the item already has evidence.

Change B: agent-requested action¶

Ask Copilot:

Move API-204 from in-progress to review. Change only that item.

Check:

WEB-318 is ready;
API-204 is review;
DOC-101 is still planned;
the visible state and response agree.

Compare the before and after values in the canvas state.

Checkpoint 4: One human action and one agent-requested capability changed the same state model without breaking the contract.

Part 5: Check rejection and recovery (20 minutes)¶

Request:

Move DOC-101 to ready.

Expected result:

Rejected: evidence is required before ready.

Check that DOC-101 remains planned.

Now add this synthetic evidence:

docs://operator-guide-review

Retry the same status change. It should succeed.

Record:

state before the request;
rejection text;
evidence added;
final accepted state.

If the first request succeeds, stop. Restore the validation rule and repeat the case. Do not approve a canvas that reaches ready without evidence.

Checkpoint 5: Recovery corrected the data and kept the rule.

Part 6: Inspect and hand off (20 minutes)¶

Exchange canvases with another group. Inspect:

artifact location and scope;
state and defaults;
visible human actions;
agent-callable capabilities;
rejection and recovery records;
dependencies and persisted data;
owner and retirement trigger.

Fix contract mismatches. Pause if access, behavior, data, or ownership remains unresolved. Then compare the final state with ../solution/final-state.json.

Checkpoint 6: The canvas matches the contract, with no unresolved access, behavior, data, or ownership issues.

Final deliverable¶

Your work is complete when another person can identify:

the selected extension scope;
the fixed canvas contract;
the prepared starting state;
both accepted changes;
the rejected change and recovery.

Troubleshooting¶

Issue	Response
`/create-canvas` is unavailable	Stop the lab.
Project scope is blocked	Use user scope.
Generated actions exceed the contract	Remove them before testing.
State and agent response disagree	Stop and inspect the shared artifact.
Local tests fail before edits	Record the failure and restore the supplied starter files.
`ready` accepts empty evidence	Fix the rule before review.

Solution reference¶

../solution/ contains the worked contract and final state.

Optional variant: Feature Workbench¶

Use this variant only after the default delivery-readiness lab, or when the trainer assigns it as follow-up practice. It does not replace the required deliverable.

Open starter/feature-workbench-contract.md.
Load the synthetic checks from starter/feature-workbench-sample.json.
Decide whether FEAT-204 should pass the test gate.
Record the required check that blocks the decision.
Compare your review with solution/feature-workbench-solution.md and solution/feature-workbench-final-state.json.

The canvas may propose pass, hold, or rerun. A named human reviewer owns the final decision. Do not connect a live CI system, merge code, or trigger deployment.