U27-S04 // Handoff Engine

Handoff Engine converts objectives and context summaries into agent-ready work packets.

U27-S04
HANDOFF ENGINE

CLASS: SYSTEM
OPERATING_POSITION: 04/08
FUNCTION: Agent Handoff + Work Packet Generation
REF_ID: U27-S04-HANDOFF-ENGINE

Release Status

SOURCE_STATUS: PUBLIC_PACKAGE ACCESS_STATUS: CLEARED_FOR_EXTERNAL_USE

This repository is a released Unit27 field kit: visible, inspectable, and intended for orientation, testing, and practical use. Controlled protocol materials remain outside this source package.

It answers one narrow question:

What exactly should the agent do with this context, under what constraints, and how will completion be checked?

Why Use It

Use Handoff Engine after context has been prepared and before implementation begins, when an AI agent needs a precise work packet instead of a loose instruction.

It is useful when the objective is known, the relevant context has been gathered, and the next risk is drift: touching the wrong files, expanding scope, skipping acceptance checks, or claiming completion before proof exists.

Example:

Problem: The agent has context, but the actual work order is still vague.
Result: Handoff Engine writes a handoff packet with objective, constraints, acceptance checks, proof cases, and launch-gate guidance.

60-Second Start

The current public release is GitHub-first. Run it from a local checkout:

git clone https://github.com/unit27research/unit27-handoff-engine
cd unit27-handoff-engine
pip install -e .
handoff-engine demo
cat handoff-engine-demo/u27/HANDOFF_PACKET.md

On your own repo:

handoff-engine init
handoff-engine build \
  --objective "Add README usage section" \
  --context context_report.json \
  --allowed README.md \
  --constraint "Keep public claims inside recorded proof." \
  --acceptance "README includes a runnable command example." \
  --proof-case readme-usage-present
handoff-engine inspect u27/handoff.json

What It Does

Handoff Engine writes:

1. u27/handoff.json
2. u27/HANDOFF_PACKET.md
3. evals/proof_cases.json

It is designed to feel like a deterministic agent handoff generator, not a project manager, code reviewer, or proof recorder.

System Position

Stack Engine -> Context Engine -> Knowledge Readiness -> Handoff Engine -> Eval Bench -> Proof Ledger -> Boundary Engine -> u27-check

Handoff Engine sits after Knowledge Readiness classification and before eval execution. It turns approved context into bounded work packets; it does not decide whether the project should exist, scan the repository, run the work, record proof, or certify the result.

Dogfood Artifacts

This repository includes a Unit27 system-order dogfood pass against itself:

1. u27/context_report.json
2. u27/context_manifest.md
3. u27/handoff.json
4. u27/HANDOFF_PACKET.md
5. u27/proof_ledger.json
6. u27/PROOF_PACKET.md
7. u27/BOUNDARY_REGISTER.md

The launch-gate role is recorded as an applicability assessment. Handoff Engine is a CLI field kit, not a web launch surface, so no u27-check launch-pass claim is made.

CLI

handoff-engine init
handoff-engine build --objective "Add README usage section"
handoff-engine inspect u27/handoff.json
handoff-engine demo

Build options:

handoff-engine build \
  --root . \
  --objective "Add README usage section" \
  --context context_report.json \
  --allowed README.md \
  --blocked .github/workflows/ci.yml \
  --constraint "Keep public claims inside recorded proof." \
  --acceptance "README includes a runnable command example." \
  --proof-case readme-usage-present \
  --boundary-note "Do not claim production readiness."

Exit codes:

0 = success
2 = input or inspection error

Artifact Shape

objective -> context summary -> scope -> constraints -> acceptance checks -> proof cases -> handoff packet

The JSON file is the durable machine-readable work order. The Markdown packet is the reviewer-facing export. The proof cases give Proof Ledger a starter set of claims to record after implementation.

Reliability

Handoff Engine is released as part of the Unit27 public tooling channel. CI verifies the unit test suite and wheel contents before changes are considered ready.

What It Does Not Do

Handoff Engine does not:

1. Decide whether the project is worth building
2. Scan the whole repo for context
3. Run tests or demos
4. Record proof
5. Rewrite public claims
6. Perform launch QA
7. Replace Eval Bench, Proof Ledger, Boundary Engine, or u27-check

Verify

PYTHONPATH=src python3 -m unittest discover -s tests
handoff-engine demo
handoff-engine inspect handoff-engine-demo/u27/handoff.json

Acceptance

PYTHONPATH=src python3 -m unittest discover -s tests
PYTHONPATH=src python3 -m handoff_engine.cli demo --root examples/sample-project
PYTHONPATH=src python3 -m handoff_engine.cli inspect examples/sample-project/u27/handoff.json
python3 -m pip wheel . --no-deps --no-build-isolation -w /tmp/handoff-engine-wheel
python3 scripts/verify_wheel.py /tmp/handoff-engine-wheel/unit27_handoff_engine-0.1.0-py3-none-any.whl

License

MIT