Agent File Handoff

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

Metadata

Field	Value
Source site	aiwikis.org
Source URL	https://aiwikis.org/
Canonical AIWikis URL	https://aiwikis.org/files/aiwikis/raw-system-archives-uaix-recent-work-sweep-2026-05-03-uai-file-handoff-u-f77270a6/
Source reference	`raw/system-archives/uaix/recent-work-sweep/2026-05-03/.uai/file-handoff.uai`
File type	`uai`
Content category	`uai-system`
Last fetched	`2026-05-03T02:48:13.1276041Z`
Last changed	`2026-05-02T19:39:10.2817513Z`
Content hash	`sha256:f77270a6f03eac061aad336e03420b0a9e63e30d9eda04feee5e2ecc75593dc7`
Import status	`unchanged`
Raw source layer	`data/sources/aiwikis/raw-system-archives-uaix-recent-work-sweep-2026-05-03-uai-file-handoff-uai-f77270a6f03e.uai`
Normalized source layer	`data/normalized/aiwikis/raw-system-archives-uaix-recent-work-sweep-2026-05-03-uai-file-handoff-uai-f77270a6f03e.txt`

Current File Content

Structure Preview

Agent File Handoff
Purpose
Active Buckets
Current Local Behavior
Recent Dispositions
Disposition Values
Implementation Levels
Required First Response Behavior
Bucket Meaning
Routes
Blocked Executable Extensions
ZIP Package Preflight Rule
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-05-02"
status: active
author: "UAIX maintainers"
version: 15
---

# 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 should be copied into AIWikis.org under `[local path redacted]` and left in the UAIX archive unless the human explicitly asks for cleanup after transfer evidence and discoverability are verified. The AIWikis pickup must preserve source path, final memory path, file count, 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.

The same evidence rule applies when a human explicitly asks to move bulky UAIX internal knowledge out of hot context and into AIWikis long-term memory. The 2026-05-01 internal memory reorganization copied selected docs and pre-slim handoff snapshots into AIWikis `raw/system-archives/uaix/internal-memory-reorg/2026-05-01/` and recorded `raw/system-archives/2026-05-01-uaix-internal-memory-reorg.json` before UAIX source notes were slimmed.

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.

## Active Buckets

- `agent-file-handoff/Content/` is active intake for candidate public/editorial material only after review.
- `agent-file-handoff/Improvement/` is active intake for audits, QA findings, SEO reports, bug notes, roadmap suggestions, and site-fix work.
- `agent-file-handoff/Archive/` is a dead archive for already-dispositioned source files and is ignored during routine intake.

## 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.
- Internal cold-memory archive: AIWikis `raw/system-archives/uaix/internal-memory-reorg/2026-05-01/` for the reviewed 2026-05-01 context-token cleanup.
- 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`.

## Recent Dispositions

- 2026-05-02: `agent-file-handoff/Content/Agentic harnesses strategy and market report for.md` was reviewed as low-risk markdown with checksum `da5a19a8f22b0e43a8a9ab280fea56ee87983f4a4f71529424a74b3923661925`; disposition `apply-now` into `/en-us/guides/agentic-harnesses-uai/`, guide navigation, discovery manifests, tests, zh-CN page override, and handoff/docs state.
- 2026-05-02: `agent-file-handoff/Improvement/Agentic harnesses strategy and market report for.md` had the same checksum and useful content as the Content copy; disposition `archive-as-duplicate` after the Content copy was applied.

## Disposition Values

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

- `apply-now`
- `convert-into-roadmap-progress`
- `archive-as-duplicate`
- `defer-with-reason`
- `ask-for-clarification`
- `block-as-unsafe-or-out-of-scope`

`TODO` may appear only in the generated index before review. It is not a disposition and does not approve, trust, publish, or execute the file.

## 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.

## Required First Response Behavior

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.

## Blocked Executable Extensions

These extensions are blocked from automatic execution and must be handled only as untrusted review inputs:

- `.bat`
- `.cmd`
- `.exe`
- `.msi`
- `.phar`
- `.php`
- `.php3`
- `.php4`
- `.php5`
- `.phtml`
- `.ps1`
- `.sh`

## ZIP Package Preflight Rule

Treat `.zip` and package drops as high risk until a local preflight records archive size, file count, unpacked size, path traversal checks, executable/script payload checks, and allowed target paths. Do not extract or run package contents as part of routine intake; review metadata first and use a controlled temporary location only when a human-approved task requires inspection.

## 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 one disposition: `apply-now`, `convert-into-roadmap-progress`, `archive-as-duplicate`, `defer-with-reason`, `ask-for-clarification`, or `block-as-unsafe-or-out-of-scope`.
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, copy original processed files first, preserve source path, final memory path, file count, checksum, disposition, actor, timestamp, and transfer evidence, update the AIWikis history/log/index or wiki graph, and remove the UAIX source archive copy only if the human separately requests cleanup after that evidence exists.

## Related Public Routes

- `/en-us/specification/project-handoff/`
- `/en-us/guides/agentic-harnesses-uai/`
- `/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 aiwikis.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; Active Buckets; Current Local Behavior; Recent Dispositions; Disposition Values; Implementation Levels; Required First Response Behavior. 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-05-03T02:48:13.1276041Z
Source origin: current-source-workspace
Retrieval method: local-source-workspace
Duplicate group: sfg-465 (primary)
Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "Agent File Handoff",
    "source_site":  "aiwikis.org",
    "source_url":  "https://aiwikis.org/",
    "canonical_url":  "https://aiwikis.org/files/aiwikis/raw-system-archives-uaix-recent-work-sweep-2026-05-03-uai-file-handoff-u-f77270a6/",
    "source_reference":  "raw/system-archives/uaix/recent-work-sweep/2026-05-03/.uai/file-handoff.uai",
    "file_type":  "uai",
    "content_category":  "uai-system",
    "content_hash":  "sha256:f77270a6f03eac061aad336e03420b0a9e63e30d9eda04feee5e2ecc75593dc7",
    "last_fetched":  "2026-05-03T02:48:13.1276041Z",
    "last_changed":  "2026-05-02T19:39:10.2817513Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-465",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-05-03T02:48:13.1276041Z"
}