Appendix C. Handoff-Package Template

C.1 What a handoff is for

At the handoff you give your project to someone who was not there, and you receive someone else's. The package is the only context the inheritor starts with. It is the human-scale version of the structured handoff an agent needs between sessions, and it tests whether your project's knowledge is written down or lives in your head (Chapter 10; prediction P8). Grading of inherited work is relative to the project as received, which the inheritor documents with characterization tests (Section C.7).

The package lives in the repository, but not in one folder. Each item sits where Table C.1 says: the specification, convention file, decision records and work log keep their working locations, and handoff/ holds the items that have no other home (the README, risk register, baseline record and characterization-test pointers). Tag the handoff commit and date the tag.

C.2 Package contents

Eight items: the six core items of Chapter 18 (Section 18.4.1) plus the baseline record and the characterization-test pointers. Table C.1 says where each goes and the test of whether it is present and complete. It is the checklist for scoring a package (Chapter 18, Section 18.4.5): the completeness score is the number of items complete out of eight. Completeness is a coarse proxy, because a long but unhelpful decision record is still present, so Section C.8 adds a quality rubric.

Table C.1. The handoff package.

What each item must carry:

1. Specification and backlog. The executable specification (Chapter 4), its non-goals, the acceptance properties, and the backlog in priority order. Mark which items are done, deferred and abandoned, and why.
2. Convention file. The conventions an agent must follow in this repository (naming, structure, testing, commands). Include a Do Not section: the things an agent must never do here, each with the reason. A rule without a reason is a rule an inheritor will delete.
3. Architecture decision records. One short record per significant decision: the context, the decision, the alternatives rejected, the consequences. Include decisions you reversed.
4. Risk register. Both parts (Appendix D), with the incidents so far logged against their IDs.
5. Work log. The files of Appendix B, complete, including the defect records.
6. Open issues. Every known defect, every unresolved question, every place where you stopped. Say what you tried.
7. Baseline record. The state of the tools and settings when the project was last known to work (Section C.3).
8. Characterization-test pointers. The tests, or the places to write them, that pin down behavior the inheritor must not change by accident. Name the behavior, not only the file.

C.3 The baseline record

Behavior depends on more than the source (Chapter 14). Record, as of the handoff commit, the baseline manifest of Chapter 14 (Section 14.5.1), which pins each item below by exact version or digest. Never record an alias for a model.

• Model: the exact model ID and settings the harness reports, and the date you last ran it.
• Harness: name and exact version, and the settings that change its behavior.
• Convention files and skills: their paths, digests and the commit they were last changed.
• Prompts: the system prompt, mission template and standing prompts.
• Permissions: what agents may read, write, run and send; the autonomy tier; which actions need your approval.
• Tools: MCP and other tool configurations, with pinned versions.
• Dependencies: lock file, and the runtime and tool versions.
• Change policy: the policy file and its owner.
• Known-good evidence: the test, evaluation and qualification results at the handoff commit, and how to reproduce them.

Add the configuration records that Chapter 14 asks for at handoff (Section 14.6, Part A):

• Baseline history: each baseline since the first, and what changed.
• Recertification results: the pass rule and results for the last model, harness or configuration change.
• Provenance coverage: the share of agent commits in the last 30 days carrying every required trailer (Appendix F, Section F.4).
• Drift list: anything in use that the manifest does not list (a skill, a permission, a tool).
• Open change requests: pending changes and known deviations.

If a model is later changed, the inheritor recertifies against this record (Chapter 14).

C.4 README skeleton for the inheritor

The README is the first thing the inheritor reads. Fill in every field, and write "none" where none applies; a blank field says nothing.

# <Project name>: handoff README        Author: __  Date: __
1. What this system does, in three sentences.
2. How to run it and how to run the tests (exact commands).
3. Where the truth lives: spec, ADRs, convention file, log.
4. State of the work: done / in progress / deferred, and why.
5. The three things most likely to surprise you.
6. The five most dangerous places to change, and why.
7. What the agent gets wrong in this repository.
8. Baseline: model, harness, permissions (see baseline record).
9. Open issues I could not close.
10. How to ask me a question (Appendix C, Section C.5).

Items 5, 6 and 7 are the ones a package usually omits and an inheritor most needs.

C.5 The logged-question protocol

The inheritor may ask the original author questions, but only through a logged channel: an issue thread in the inherited repository. Each question is evidence of something the package did not carry.

For the inheritor. One question per issue, titled Q: <topic>. Include:

• what you were trying to do and what you already tried,
• the file or artifact you looked in first,
• your best guess at the answer, so the author can confirm or correct it.

For the original author. Answer in the same thread. Say whether the answer was written anywhere in the package. If it was, say where; if not, say so plainly.

For both. Class each question when it is asked, and again at the end of the project, as one of Chapter 18's three classes (Section 18.4.2). Label the issue:

1. package-answered: the package already answered it, and the inheritor missed it;
2. package-should-have: the package should have answered it, because the information was the kind a package can hold, and it was not there;
3. package-could-not: the answer needed the author's judgment or lives only in the author's memory, and no package could have held it.

A fourth label, out-of-scope, marks a question the package should not answer at all. It is outside the class count: do not include it in the counts of the three classes.

The inheritor copies each question into the work log with its label and the minutes it cost. The count in each class, with the comprehension hours, is the measurement of Chapter 18, Section 18.4.5. The count of package-should-have questions is the cleanest measure of how much the package left out. Do not ask by any other channel. If a hallway answer matters, write it into the thread afterward.

C.6 The inheritor's handoff-audit questions

The handoff audit (milestone M5) is your written assessment of the package you received. Before you change anything, answer these five questions of Chapter 18 (Section 18.4.4) in writing, with evidence for each. The audit goes to the original author, who answers it in the oral defense (Appendix G, Section G.5).

1. Rebuild. Could you rebuild the baseline from the package alone? Start with the five configuration checks of Chapter 14 (Section 14.5.6): the manifest resolves, provenance coverage, rebuild and rerun, drift, open changes. Say how long it took.
2. Use. Which package items did you use, and did each help? Go item by item through Table C.1.
3. Questions. How did you class each of your questions (Section C.5)? Give the count in each class.
4. Comprehension. How many comprehension hours did you spend, and on what?
5. Biggest miss. What is the one thing the package missed that cost you the most?

Rate each answer by where the evidence was: found in the package, found elsewhere, or not found.

Optional prompts. These are not part of the audit. Use them to find the evidence behind your five answers.

• Does every backlog item link to an acceptance property or a check?
• Do the acceptance tests pass on a clean checkout of the handoff commit?
• Does the "Do Not" section give a reason for every rule? Did you test whether an agent obeys it?
• For each ADR: does the code still match the decision?
• Can you find, in the package, why the most important design choice was made?
• Does the risk register's Part B list every path where an agent touches private data, untrusted content or external communication? Did you find one it missed?
• Is the baseline record enough to reproduce the agent's behavior? What is missing?
• Does the work log run unbroken? Where are the gaps?
• What does the system do that no spec, ADR or test says it should?
• Which behaviors would you pin with characterization tests before touching them? List them first.

C.7 The as-received baseline

Before your first change, write characterization tests that record what the system does now, including behavior you believe is wrong. Commit them, tag the commit, and record the date. Your inherited work is graded relative to this baseline, so a weak inheritance does not count against you. A defect that was present at the baseline goes in the log with introduced_at set to the original author's stages, not yours.

C.8 Scoring the package, and measuring the inheritance

Chapter 18 (Section 18.4.5) asks for three things beyond the completeness count of Table C.1: a quality rubric, a complexity measure, and care in reading the correlations. All three are exploratory at the size of a class.

The quality rubric. Score each of the eight items from 0 to 2 on each of three questions, so an item scores 0 to 6 and a package 0 to 48. The inheritor scores accuracy and specificity at intake, before changing anything, and usefulness at the end; the instructor re-scores a sample. Report the completeness count and the rubric total side by side, and never merge them.

Table C.2. The handoff quality rubric.

A present-but-wrong item scores 0 on accuracy and lowers the total, which is the case completeness alone cannot see. Chapter 14's configuration measures (a manifest that resolves, trailer coverage, a recertification record, a drift list, an eval suite that runs with one command) are reported beside this score, not inside it.

Complexity, not line count. Raw line count poorly measures what the inheritor had to understand: ten thousand lines of generated data classes are not ten thousand lines of tangled logic. Record a repository complexity measure that your instructor fixes in advance (for example modules, external dependencies and branching decisions). Report comprehension hours per thousand lines and per unit of that measure, and control for reading speed with the inheritor's own earlier review rate (Appendix B, Section B.7).

Reading the correlations. Report the scatter, a rank correlation between score and comprehension hours, and its interval, for completeness and for the rubric total separately. A class of 25 gives a suggestive pattern at most, so call the result neither a confirmation nor a refutation of P8. Package length is a rival explanation; correlate it too, and see whether fullness predicts hours when length does not.