Context handoff: Maintenance and verification

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.yaml are 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.