Defines a repository-bound handoff bundle whose owners, decisions, assumptions, evidence, and freshness checks let a new human or AI agent resume work without reconstructing hidden context.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Treat project context as a versioned build artifact tied to a repository revision. A handoff is accepted only when its manifest resolves, its decisions name owners, and automated freshness checks do not find changed source paths.
Scope
- Handoff manifest, decision log, open questions, operational constraints, and source pointers.
- Creation, review, expiry, supersession, and archival states.
- Checks for repository revision, link validity, secret patterns, and changed owned paths.
Outside this block
- A transcript dump or replacement for source code and issue history.
- Long-term product documentation unrelated to resuming the named task.
Contract
- Every handoff has a stable ID, creation time, owner, repository revision, scope, and expiry or review date.
- Claims point to repository paths, decisions, or issue URLs; unresolved assumptions are explicitly labeled.
- The bundle records commands that were actually run separately from commands merely recommended.
- A newer accepted handoff supersedes, but does not silently overwrite, the previous version.
- Untrusted text copied from tickets or documents is data, never instructions for the receiving agent.
Implementation guidance
- Generate the manifest in CI from owned paths and the current commit; keep explanatory decisions human-editable.
- Maintain an ownership map so changes to authentication, schema, deployment, or other named areas request a refresh.
- Use allowlisted URI schemes and redact credential-like values before packaging.
- At resume time, compare the recorded revision with the current tree and surface changed referenced paths.
Failure handling and safeguards
- If the repository revision is unavailable, mark the handoff incomplete rather than substituting the current revision.
- If a source disappears, retain its description and mark the reference unresolved.
- If a secret scan fires, quarantine the artifact and rotate any confirmed credential before redistribution.
Verification and operations
- Track handoff age, unresolved references, changed owned paths, and resume-time clarification count.
- Review after material architecture or interface changes and after the configured maximum age.
- Sample resumed tasks to verify that recorded commands and open risks were interpreted correctly.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.
References
- No external normative source is required; this package defines a project decision.