Agent File Handoff

--- title: "Agent File Handoff" description: "UAIX dogfoods chat-start file intake as part of Project Handoff." slug: "uaix/uai-system/files/uai-file-handoff-uai-ec41fb98" status: "working-draft" trust_level: "generated-evidence" source_status: "current-source-file" content_type: "source-file" generated_by: "tools/sync-source-files.ps1" last_reprocessed: "2026-04-30" source_site: "uaix.org" source_url: "https://uaix.org/" canonical_url: "https://aiwikis.org/uaix/uai-system/files/uai-file-handoff-uai-ec41fb98/" canonical: "https://aiwikis.org/uaix/uai-system/files/uai-file-handoff-uai-ec41fb98/" source_reference: ".uai/file-handoff.uai" file_type: "uai" content_category: "uai-system" content_hash: "sha256:ec41fb9892182d144f08790594907faad336554d3d8d7b09ddd046ff7b500544" last_fetched: "2026-04-30T22:07:25.2671233Z" last_changed: "2026-04-30T18:27:03.8777740Z" import_status: "unchanged" duplicate_group_id: "sfg-136" generated_explanation: true explanation_last_generated: "2026-04-30T22:07:25.2671233Z" source_domains:

tags:

related_files:

---

"uaix.org"
"ai-memory"
"provenance"
"uaix"
"uai"
"retrieval"
"prompt-size-minimization"
""

Agent File Handoff

UAIX dogfoods chat-start file intake as part of Project Handoff.

Metadata

Field	Value
Source site	uaix.org
Source URL	https://uaix.org/
Canonical AIWikis URL	https://aiwikis.org/uaix/uai-system/files/uai-file-handoff-uai-ec41fb98/
Source reference	`.uai/file-handoff.uai`
File type	`uai`
Content category	`uai-system`
Last fetched	`2026-04-30T22:07:25.2671233Z`
Last changed	`2026-04-30T18:27:03.8777740Z`
Content hash	`sha256:ec41fb9892182d144f08790594907faad336554d3d8d7b09ddd046ff7b500544`
Import status	`unchanged`
Raw source layer	`data/sources/uaix/uai-file-handoff-uai-ec41fb989218.uai`
Normalized source layer	`data/normalized/uaix/uai-file-handoff-uai-ec41fb989218.txt`

Current File Content

Structure Preview

Agent File Handoff
Purpose
Current Local Behavior
Implementation Levels
First Response Pattern
Bucket Meaning
Routes
Trust Boundary
Non-Goals
Portability Boundary
Publication Boundary
Required AI Behavior
Related Public Routes

Raw Version

Local absolute paths are redacted in this public view. The source hash and source-side raw layer are based on the unredacted source file.

---
uaix: "1.0"
type: operations
title: "Agent File Handoff"
created: "2026-04-27"
updated: "2026-04-30"
author: "UAIX maintainers"
version: 11
---

# Agent File Handoff

## Purpose

UAIX dogfoods chat-start file intake as part of Project Handoff.

The short concept is: an inbox for AI project handoff, with a strict trust boundary.

Project Handoff tells the next AI what the project is. Agent File Handoff tells the next AI what new loose files arrived since the last handoff. The standard is: visible, reviewed, dispositioned.

A dropped file is not part of handoff until it is:

1. Visible in active intake.
2. Reviewed by the next AI.
3. Given a disposition.
4. Promoted or archived.

Humans and other AI systems can drop files into two intent buckets:

- `agent-file-handoff/Content/` for candidate public content, article drafts, page copy, public source material, and editorial material that might become a site route after review.
- `agent-file-handoff/Improvement/` for audits, SEO reports, QA findings, bug notes, screenshots of broken UI, roadmap suggestions, and other work items for improving the site.

Processed files move to `agent-file-handoff/Archive/` after an explicit disposition. The archive is retained only for human reference or repossession. It is dead to routine AI intake: agents must not scan, summarize, index, or reprocess archived files unless a human explicitly names an archived file or moves it back into `Content/` or `Improvement/`.

Cross-site archive consolidation is a separate explicit workflow. When a human asks for processed archives to become long-term system memory, UAIX archive files may be moved into AIWikis.org under `[local path redacted]` and removed from the UAIX archive only after a transfer manifest or equivalent evidence is recorded. The AIWikis pickup must preserve source path, final memory path, checksums, original disposition, actor, timestamp, and transfer evidence, then update AIWikis history, log, index, or wiki graph so the final resting place is discoverable. It should also update the AIWikis Intake Outcome Ledger, currently `content/pages/016-intake-outcome-ledger.md` and after deployment `/intake-outcome-ledger/`, so the human can see what happened to the file and where reviewed change documentation lives. The AIWikis copy is memory/provenance evidence, not canonical UAIX public truth.

A new AI should scan both buckets while loading `AGENTS.md` and the listed `.uai` files, before broad planning. This keeps newly supplied files visible even when the human prompt does not mention them.

Visibility is not enough. If `.uai/intake-index.uai` lists any non-blocked file, the AI must inspect the file immediately, summarize it, and give it an explicit disposition before unrelated broad work continues.

Digest means the active file has been read, summarized, risk-checked, routed to a target surface or rejection reason, and captured into the appropriate durable state before the source file leaves active intake.

This solves two failures at once: a file can be present but invisible if it is not indexed or referenced, and a file can be indexed but still ignored if the AI does not inspect and disposition it.

The requirement is the AGENTS.md-triggered intake behavior. `scripts/Invoke-UaiFileIntake.ps1` is the local helper for refreshing the index. Watchers, daemons, queue folders, manifests, background services, cron loops, out-of-chat auto-pickup processes, and bucket-local README instructions are discouraged because the pattern must remain portable across languages and environments.

## Current Local Behavior

- Content bucket: `agent-file-handoff/Content/`
- Improvement bucket: `agent-file-handoff/Improvement/`
- Archive folder: `agent-file-handoff/Archive/`
- Downstream long-term archive: `[local path redacted]` after explicit human-directed consolidation.
- Legacy compatibility folder: `agent-file-handoff/intake/`
- Chat-start index helper: `scripts/Invoke-UaiFileIntake.ps1`
- Generated index: `.uai/intake-index.uai`
- No watcher/daemon helpers, queue folders, routine pickup manifests, or background services are part of this workspace's intake pattern. Transfer manifests are allowed only for explicit archive consolidation into long-term memory.

The intake pass computes SHA-256 checksums, assigns bucket names and route hints, marks non-executable files as `needs-agent-review`, and updates the index. It does not move files, publish files, create review drafts, or mark dropped files trusted.

The legacy `agent-file-handoff/intake/` folder is retained only so old instructions have a place to point. Files left there are treated as `Unsorted` and should be moved, applied, deferred, clarified, or blocked before broad work continues.

The archive folder is intentionally excluded from `.uai/intake-index.uai`. Do not create bucket README files or rely on folder-local instructions there; durable AI behavior belongs in `AGENTS.md` and `.uai` files, and human-facing explanation belongs in root `readme.human`.

The required agent disposition for every `needs-agent-review` file is one of:

- Apply now because it is directly relevant and safe.
- Convert into roadmap, progress, decision, issue, or implementation state because it is useful but not public content.
- Convert into public content only when it is in the `Content` bucket and passes source, route, support-boundary, and release checks.
- Archive as duplicate when the file exactly or substantially duplicates already-dispositioned material; record the duplicate relationship and cite the prior disposition before archiving.
- Defer with a concrete reason.
- Ask the human for clarification.
- Block as unsafe, unsupported, out of scope, or executable/script-like.

## Implementation Levels

- Level 1: Manual. `AGENTS.md` requires the AI to inspect `Content/` and `Improvement/` at chat start. No script is required, but every active file still needs summary, risk review, and disposition before broad work.
- Level 2: Indexed. A local helper refreshes `.uai/intake-index.uai` with paths, bucket names, route hints, sizes, checksums, status, and risk. The helper remains local only and does not publish, trust, certify, or move files.
- Level 3: Release-integrated. Disposition can update roadmap, progress, release notes, public copy, or implementation work after normal review. This still is not automatic publication, and release/package checks run only when the target requires them.

## First Response Pattern

When intake files exist, include this shape before broad unrelated work:

```text
File intake found:
1. agent-file-handoff/Content/example.md
   - Summary:
   - Risk:
   - Recommended disposition:
   - Target surface:
   - Checks needed:
```

When no files are pending, say:

```text
File intake checked:
No active Content or Improvement files require review.
```

## Bucket Meaning

- `Content` means the file might become public-facing copy, a public page, a report, an example, or editorial source material after review.
- `Improvement` means the file is about fixing, auditing, prioritizing, or improving the site. It should become roadmap/progress state, an issue, a code change, a QA check, or an implementation note, not public copy by default.
- `Archive` means the file already received a disposition. Leave it alone during normal AI handoff. A human can reference it by exact path or move it back into an intake bucket to repossess it.
- `Unsorted` means the file was dropped into the legacy `intake/` folder and needs human or agent classification before promotion.

## Routes

- `site-content-draft` for text-like files in `Content/`.
- `site-improvement-report` for text-like files in `Improvement/`.
- `handoff-context` for `.uai`, `.json`, `.yaml`, and `.yml`.
- `content-asset-review` or `improvement-evidence-review` for PDFs and images, depending on bucket.
- `package-review` for `.zip`.
- `content-data-review` or `improvement-data-review` for `.csv` and `.tsv`, depending on bucket.
- `document-review` for `.docx`, `.pptx`, and `.xlsx`.
- `source-review` for source code files. Review only; do not execute.
- `unsorted-review` for old files left in `intake/`.

Executable/script-like drops are reported as `blocked-local-review` in the index and must not be executed or promoted.

## Trust Boundary

- Visibility is not trust.
- Indexing is not approval.
- Archive is not certification.
- Checksums are identity evidence, not truth evidence.
- Route hints are suggestions, not publishing authorization.
- Executable files must never be run automatically.
- Dropped files may contain secrets, private data, malware, unsupported claims, copyrighted material, or inaccurate instructions.
- Promotion requires a named target and normal review for that target.

## Non-Goals

Agent File Handoff is not a public upload system, hosted validator, certificate, SDK, daemon, watcher, trust engine, public sitemap, media library, automatic publishing system, human-review substitute, official `.uai` generator, or replacement for UAI-1 message exchange.

## Portability Boundary

The handoff contract is a one-shot intake scan and review gate during `AGENTS.md` load. A project can implement that scan in any language or perform it manually, as long as both `Content/` and `Improvement/` are inspected, `Archive/` is ignored, `.uai/intake-index.uai` is updated, and every listed file has a named disposition before unrelated broad work begins.

## Publication Boundary

Public page changes, WordPress writes, release packages, and production deployment still require the normal project constraints, verification checks, and explicit approval path. Do not treat a dropped file as public truth just because it passed local intake, especially when it came from `Improvement/`.

## Required AI Behavior

At the start of a broad task:

1. Read `AGENTS.md`.
2. Check `agent-file-handoff/Content/` and `agent-file-handoff/Improvement/`, then refresh the index. Use `scripts/Invoke-UaiFileIntake.ps1` when available.
3. Load the listed `.uai` files, including the refreshed `.uai/intake-index.uai`.
4. Inspect each `needs-agent-review` file named in the index before unrelated broad work.
5. Summarize each file and state a disposition: apply now, convert to durable state, defer with a reason, ask for clarification, or block.
6. Move already-dispositioned intake files into `agent-file-handoff/Archive/` when their useful information has been captured or explicitly rejected.
7. Promote useful content into canonical docs, public pages, roadmap state, or release evidence only after checking constraints and support boundaries.
8. If a human explicitly asks AIWikis to consolidate processed archives, preserve source path, final memory path, checksum, disposition, actor, timestamp, and transfer evidence, update the AIWikis history/log/index or wiki graph, and remove the UAIX source archive copy only after that evidence exists.

## Related Public Routes

- `/en-us/specification/project-handoff/`
- `/en-us/specification/agent-file-handoff/`
- `/en-us/specification/agents-md/`
- `/en-us/tools/uaix-agents-protocol/`
- `/en-us/roadmap/`

Why This File Exists

This is a UAI AI Memory handoff file from uaix.org. It is shown here because AIWikis.org is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This .uai file is a compact operations packet. It keeps one kind of durable project truth separate from the rest of the archive so an agent can load the topic it needs without pulling the whole project history into prompt context.

Structure

The file is structured around these visible headings: Agent File Handoff; Purpose; Current Local Behavior; Implementation Levels; First Response Pattern; Bucket Meaning; Routes; Trust Boundary. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
Crawlers should treat the AIWikis page as transparent evidence and follow the source URL/source reference for authority boundaries.
Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Provenance And History

Current observation: 2026-04-30T22:07:25.2671233Z
Source origin: current-source-workspace
Retrieval method: local-source-workspace
Duplicate group: sfg-136 (primary)
Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "Agent File Handoff",
    "source_site":  "uaix.org",
    "source_url":  "https://uaix.org/",
    "canonical_url":  "https://aiwikis.org/uaix/uai-system/files/uai-file-handoff-uai-ec41fb98/",
    "source_reference":  ".uai/file-handoff.uai",
    "file_type":  "uai",
    "content_category":  "uai-system",
    "content_hash":  "sha256:ec41fb9892182d144f08790594907faad336554d3d8d7b09ddd046ff7b500544",
    "last_fetched":  "2026-04-30T22:07:25.2671233Z",
    "last_changed":  "2026-04-30T18:27:03.8777740Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-136",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-04-30T22:07:25.2671233Z"
}

Agent File Handoff

Agent File Handoff

Metadata

Current File Content

Structure Preview

Raw Version

Why This File Exists

Role

Structure

Prompt-Size And Retrieval Benefit

How To Use It

Update Requirements

Related Pages

Provenance And History

Machine-Readable Metadata