Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .agent/skills/aeos-handoff/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ description: Use to package an approved task packet into a bounded handoff bundl

# Hand off, return and resume

For a source-repository documentation task, use the existing packet's bounded
selection and [documentation workflow](../../../docs/DOCUMENTATION_PR_WORKFLOW.md).
Supply the complete [return and rationale contract](../../../prototypes/issue_handoff/WORKER_CONTRACT.md)
as a selected source before dispatch. A README link or Allowed Reads entry alone
does not deliver a contract. The package commands below remain the frozen route.

The handoff CLI copies only selected sources into a bundle with hashes, so the receiving assistant sees a fixed, checkable context. It never dispatches work, runs a model, authenticates approval or issues independent review. Transport is manual.

All commands run from the vault parent with `vault/09_TOOLS/agent_runner_v1/unified_handoff/handoff.py`, or from the vault root without the `vault/` prefix. Keep bundles outside the source vault.
Expand Down
6 changes: 6 additions & 0 deletions .github/workflows/issue-handoff.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ on:
paths:
- 'prototypes/issue_handoff/**'
- 'tests/**'
- 'docs/DOCUMENTATION_PR_WORKFLOW.md'
- '.agent/skills/aeos-handoff/**'
- 'distribution/agentic-engineering-os-2026.10.17-public.4/**'
- '.github/workflows/issue-handoff.yml'
workflow_dispatch:
Expand All @@ -25,6 +27,10 @@ jobs:
python-version: ${{ matrix.python }}
- name: Synthetic round trip and refusal tests (no model or paid API)
run: python -B -m unittest discover -s tests -p 'test_issue_handoff.py' -v
- name: Documentation context, freshness and return contracts
run: python -B -m unittest discover -s tests -p 'test_documentation_workflow.py' -v
- name: Public documentation packet preflight
run: python -B prototypes/issue_handoff/documentation_workflow.py lint --root . --packet prototypes/issue_handoff/documentation-task.md
- name: Frozen public.4 handoff and rationale contracts
run: python -B -m unittest discover -s distribution/agentic-engineering-os-2026.10.17-public.4/vault/09_TOOLS/agent_runner_v1/unified_handoff -p 'test_*.py' -v
- name: Frozen public.4 manifest
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ Requires Python 3.11+ (tested on 3.11.15 and 3.14.5 on Windows). Install the pac

## Explore the system

- [Documentation and PR workflow](docs/DOCUMENTATION_PR_WORKFLOW.md): bounded current context, complete worker returns, freshness checks and a local PR draft recipe in the source checkout.

![AEOS architecture: implemented file operations and manual handoffs](docs/diagrams/aeos-architecture.svg)

- [Architecture and usage flow](docs/ARCHITECTURE.md) — real file contracts, commands and manual handoffs
Expand Down
137 changes: 137 additions & 0 deletions docs/DOCUMENTATION_PR_WORKFLOW.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
# Documentation and PR workflow

Use this local recipe for a bounded change in the source checkout. It extends
the existing task packet and public.4 handoff/rationale validators; it does not
run a model, open a PR or update an operating vault. The packaged download and
the fixed synthetic issue demonstration remain separate routes.

## Authority and task inputs

Read the target's instructions, current requirements, contribution rules, issue
context and related changes. Operator-approved requirements govern intent;
current source and reproducible checks establish implemented behavior. Live
receipts establish deployed behavior. Report disagreements explicitly. Timestamps
and generated summaries cannot decide authority.

The controller supplies the repository/worktree and baseline, a v1.2 packet,
bounded reads and writes, acceptance criteria, both complete return contracts,
artifact names, required checks and an independent reviewer when applicable.
The [worker contract](../prototypes/issue_handoff/WORKER_CONTRACT.md) describes
the frozen schemas and [example packet](../prototypes/issue_handoff/documentation-task.md)
shows the local documentation pilot. The example's status records the local
exercise's scope; it does not grant a future user permission to execute it.

## Select and prepare

Put a single `context-selection` JSON fence in the existing task packet.
Each source names a relative path, logical scope, authority/purpose, lifecycle
status, replacement (or null), and exact required references. Only active
sources enter an ordinary bundle. Supersession requires a named active
replacement for the same scope. History remains accessible by named lookup.

`contracts` names the selected return and rationale documents. `dependencies`
names additional files whose changed bytes invalidate the run. `documentation`
maps changed paths to documents requiring review. `required_artifacts` and
`required_checks` name the worker's obligations. These fields are per-task
selection metadata, not another project registry. Keep stable inputs separate
from allowed outputs; an input change needs reconciliation before more work.

From the source checkout, with an approved packet and a new absolute run path
outside it:

```powershell
$root = (Get-Location).Path
$packet = 'prototypes/issue_handoff/documentation-task.md'
$workflow = 'prototypes/issue_handoff/documentation_workflow.py'
$run = Join-Path (Split-Path $root -Parent) 'aeos-doc-task-001'
python -B $workflow lint --root $root --packet $packet
if ($LASTEXITCODE -ne 0) { throw 'Resolve packet findings' }
python -B $workflow prepare --root $root --packet $packet --output $run
if ($LASTEXITCODE -ne 0) { throw 'Preparation stopped; preserve the attempt' }
python -B $workflow check --run $run
if ($LASTEXITCODE -ne 0) { throw 'Do not dispatch stale context' }
```

Read the bundle's entire execution brief, packet, selected snapshots and result
template. Use the controller-held baseline digest for the rationale report.
Give the worker only its authorized task and accessible contract files. For
native code work, use the host's bound worktree, and keep workers' write scopes
disjoint. The adapter does not create, bind or dispatch an agent session.

## Return, verify and draft

The worker implements the bounded change and updates affected documentation.
Its `artifacts/report.md` includes changed behavior, affected authorities,
evidence, unknowns and the existing `code-rationale` fence. Every changed path
has rationale or a specific `documentation-not-needed` explanation.
For a mapped no-documentation-change disposition, name each affected relative
path in that entry's `why` text so the explanation is tied to the reviewed scope.
Record checks as actually run, failed, blocked or not run; preserve negative attempts.

The controller independently reruns the prescribed checks, compares the actual
diff and artifacts, and then runs:

```powershell
python -B $workflow verify --run $run
if ($LASTEXITCODE -ne 0) { throw 'Return is incomplete or stale' }
python -B $workflow check --run $run
if ($LASTEXITCODE -ne 0) { throw 'Evidence is no longer current' }
```

Mechanical completion remains `needs-review`, with no H3 verdict. Ask a separate
reviewer to challenge the evidence and reproduce material checks. Apply the
target's H3 rules without turning worker success into independent review. Only
the controller updates authorized current-state files, after comparing claims
with evidence; retain historical reports and branch-specific limitations.

Prepare the PR title/body from the final diff: problem, resulting behavior,
checks actually run, failures and unrun checks, material limits, and appropriate
public evidence/issue links. Follow the target's title, issue-first and AI
disclosure rules. A local draft body is not an opened PR. Keep private evidence,
machine paths and owner data out of public text. Publication is a separate gate.

## Troubleshooting

- `Complete return and rationale contracts must be selected` or
`Incomplete or unsupported worker contract`: stop before dispatch. Have the
controller select the complete supported contract for both roles, then lint
and prepare a new bundle; a link or headings alone cannot supply the schema.
- `Selected source or dependency changed; reconcile in a fresh run` or
`Verification receipt is stale; reconcile in a fresh run`: inspect the drift,
preserve the old run and evidence, and have the controller prepare a fresh
authorized run and rerun affected checks. Never repair stored hashes or dates.
- `Task report needs exactly one code-rationale fence`: return one complete
rationale object covering every actual changed path against the original
controller baseline. For `Stale reference`, re-read the document and re-verify
its claims before recording its current hash and heading; preserve prior evidence.
- `Missing or nonpassing required check`: capture the prescribed command's output
and exit status. Missing, failed, blocked and `not_run` required checks prevent
verification; stop and reconcile with the controller before retrying. Keep failed
attempts, and leave optional unrun checks as `not_run` with null evidence.
The adapter validates claims; the controller must independently rerun checks.

## Design and limits

The existing packet owns selection, the bundle owns hashed snapshots, and the
existing task report owns rationale and documentation delta. Adding a second
registry or editing frozen distribution bytes would create competing authority.
The adapter therefore composes the frozen validators and validates a bounded
selection fence in the packet. The full public worker contract is selected and
checked by bytes; a heading or README link cannot supply a missing schema.

Dependency mappings identify likely review needs, not semantic correctness or
complete dependency discovery. Hashes establish identity, not truthful prose,
authenticated approval or proof that a worker ran a command. Controller checks
and independent review supply those additional observations. Root-relative path
guards reject traversal and links but are not a hostile same-user sandbox.

Read-only checks do not create new verification claims. An unchanged successful
verification reuses its receipt. Changed inputs, outputs, contracts or evidence
invalidate that receipt. Inspect the difference, preserve the old run, prepare
a fresh authorized packet and rerun affected checks. Updating a stored date or
expected digest is not reconciliation or re-verification.

Root instructions stay in `AGENTS.md`; tool-specific files are thin pointers.
Confirm the installed host actually loads them before relying on an adapter.
Neither `.gitignore` nor an archive directory prevents an agent from reading
files. This workflow demonstrates exclusion from default selected context only.
7 changes: 6 additions & 1 deletion prototypes/issue_handoff/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Git subprocesses have no stdin or shell, a 60-second timeout, captured events, n

## Manual worker return

Use `prepare` and authorized `handoff`, then omit `synthetic-worker`. Read generated `HANDOFF.md`, the bundle's full `execution_brief.md`, packet and four selected snapshots. Immediately before transport, run the public.4 checker:
Use `prepare` and authorized `handoff`, then omit `synthetic-worker`. Read generated `HANDOFF.md`, the bundle's full `execution_brief.md`, packet and five selected snapshots, including the complete return/rationale contract. The adapter pins that contract before preparation and checks it again before worker execution and verification. Immediately before transport, run the public.4 checker:

```powershell
$tools = Join-Path $repo 'distribution/agentic-engineering-os-2026.10.17-public.4/vault/09_TOOLS/agent_runner_v1/unified_handoff'
Expand Down Expand Up @@ -101,6 +101,11 @@ The controller runs `verify` after return. Never invoke the deterministic fixtur

## Evidence and acceptance

For an actual source-repository task, use the separate [documentation and PR
recipe](../../docs/DOCUMENTATION_PR_WORKFLOW.md) and its packet-bound adapter.
It reuses public.4 validation and does not change this demonstration's fixed
synthetic-only authority, create an agent session or publish a PR.

`controller/` retains issue export/normalized data, original scaffold, draft/controller/Git-locator hashes, authorization record, frozen Git identity, manifest and file/rationale baselines, started/completed command events, candidate patches and fresh verification receipts. `bundle/` contains existing public.4 context/result contracts and returned artifacts. Runtime logs include absolute paths; keep them local. Commit only public-safe synthetic summaries.

A separate reviewer who did not implement the consolidation must inspect packet/scope, reproduce all acceptance checks, inspect actual changes/patch, check every claim and record VERIFIED, PARTIAL or FAIL separately. The implementer cannot give its own result H3. Do not merge because CI is green. Owner acceptance is a separate decision. Manual provider return, local Windows 10 execution and independent H3 remain acceptance requirements.
Expand Down
92 changes: 92 additions & 0 deletions prototypes/issue_handoff/WORKER_CONTRACT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Worker input and return contract

This guide describes the existing public.4 validators, not a new result schema.
The approved task packet remains v1.2; the handoff manifest and worker result
remain v1.0. A status label is not authenticated approval. The controller supplies
the repository, branch, baseline, exact reads/writes, acceptance checks, artifact
names and this guide before dispatch. Stop if any required input is absent.

## Worker result v1.0

Use the generated `worker_result.template.json`. Its exact top-level keys are
`schema_version`, `run_id`, `task_id`, `worker`, `execution_state`, `summary`,
`artifacts`, `changed_paths`, `checks`, `risks`, `proposed_writeback`, `next_action`.
Keep `schema_version` equal to `"1.0"` and preserve the template identities.
Execution state is `ready_for_review`, `blocked`, `failed` or `cancelled`.

- Artifact: exactly `path`, `sha256`, `description`. Paths are unique ignoring
case and start with `artifacts/`. SHA-256 is 64 lowercase hexadecimal digits
matching the saved file bytes.
- Check: exactly `name`, `command`, `outcome`, `evidence`. Outcome is `passed`,
`failed`, `blocked` or `not_run`. Evidence names a declared artifact; only a
`not_run` check may have null evidence. Record unrun checks explicitly.
- Proposed writeback: exactly `target`, `artifact`, `rationale`. The target
must be authorized in Allowed Writes and the artifact must be declared.
This is a proposal, never an applied state change or approval.
- Changed paths are unique, root-relative paths within Allowed Writes.
All five list fields have at most 100 items. A ready return needs at least one
check and artifact. Summary, next action, risks, descriptions, check names and
commands, and writeback rationale are nonempty strings without `REPLACE:`.

Unknown fields and duplicate JSON keys are rejected. Result JSON is limited to
128 KiB, artifacts to 8 MiB each. Use UTF-8. Do not add an H3, approval, completion
or owner-acceptance field to a worker result.

## Rationale coverage

The controller captures task-start bytes using frozen public.4
`code_rationale.py snapshot` and retains the baseline SHA-256 outside worker
writes. Do not regenerate that baseline to make a check pass. Obtain the current
change digest with `code_rationale.py changes` using that baseline and digest.

The report has exactly one fenced `code-rationale` JSON object with exactly
`task_id`, `baseline_sha256`, `changes_sha256`, `entries`.
Each entry has exactly `paths`, `disposition`, `why`, `where_to_edit`,
`constraints`, `verification`, `references`.

- `paths` is a nonempty list. All entries together cover every actual changed
path exactly once: additions, modifications and deletions, including ignored
and untracked paths inside the frozen scope. A rename covers both paths.
- `disposition` is `documented` or `documentation-not-needed`. The latter needs
a concrete reason in `why`, tied to this change rather than a blanket waiver.
- `why`, `where_to_edit`, `constraints`, and `verification` are nonempty strings
without `REPLACE:`. Explain decisions and constraints rather than syntax.
- `references` is a list of exact objects with `path`, `sha256`, `contains`.
A documented entry requires a reference. Its relative file path must exist,
its SHA-256 must match current bytes, and `contains` must be a nonempty current
heading or symbol substring. Include every durable reference used as evidence.

The task ID and baseline digest must match the controller baseline. The changes
digest hashes the actual delta serialized by `handoff.json_bytes`: sorted keys,
two-space indentation, unescaped Unicode, trailing newline, UTF-8. Prefer the
validator's output to reimplementing this calculation.

The report lives outside the frozen editing scope and is declared as a hashed
result artifact. For `handoff.py complete`, frozen scopes equal all packet
Allowed Writes and declared changed paths equal actual rationale-covered paths.
Missing fields, stale references, incomplete coverage and changed control files
reject completion. Do not update a hash to conceal missing re-verification.

## Documentation delta and delivery

Use the task report to state changed behavior, affected authoritative documents,
captured checks and remaining unknowns. An impact mapping identifies review
needs; it does not establish semantic truth. A controller compares explanations
against the actual diff and reruns applicable checks before writing current state.

Follow the target's contribution rules, issue and related-work context, AI policy,
title and test requirements. Prepare a local PR body from the verified diff:
problem, resulting behavior, checks actually run, failures/unrun checks, material
limits and public-safe evidence links. Keep private paths and evidence out of it.
Opening a PR, publishing, merging and deploying require their own authorization.

Structural completion and rationale coverage do not prove execution or explanation
quality. Independent H3 and owner acceptance remain separate. Context exclusion
is not a filesystem sandbox. Paths retain the frozen validators' traversal,
symlink/junction, hardlink, private-name and size restrictions.

## Runtime authorities

- [Result and bundle validator](../../distribution/agentic-engineering-os-2026.10.17-public.4/vault/09_TOOLS/agent_runner_v1/unified_handoff/handoff.py)
- [Rationale validator](../../distribution/agentic-engineering-os-2026.10.17-public.4/vault/09_TOOLS/agent_runner_v1/unified_handoff/code_rationale.py)
- [Frozen rationale rule](../../distribution/agentic-engineering-os-2026.10.17-public.4/vault/09_TOOLS/agent_runner_v1/unified_handoff/CODE_RATIONALE.md)
Loading
Loading