UAIX Recursive Improvement Loops with next-recursive-prompt.uai

Full report

On this page

Executive Summary

UAIX’s public record currently defines a portable evidence and handoff layer, not an agent runtime. The reviewed materials consistently separate the execution layer from the durable memory layer: harnesses or runtimes execute work, while UAIX Project Handoff preserves reviewable project memory in repo-local files such as AGENTS.md, .uai/readme.human, and typed .uai records. Publicly reviewed UAIX materials do not specify an underlying runtime architecture, repository implementation, official automatic repository writer, hosted sync service, SDK, or CLI for this feature area; those internals are therefore unspecified in the public record reviewed here.

That separation makes a file named .uai/next-recursive-prompt.uai a strong fit for UAIX if it is treated as a derived, compact, code-scope resume artifact, not as a second source of truth. UAIX already requires compact hot context, explicit write-back of accepted truth, and code-oriented packages to carry .uai/coding-standards.uai when code or code-like artifacts are in scope. A required next-recursive-prompt.uai for code-scoped agents is therefore best designed as a small, machine-generated “resume loop” file that points to authoritative files such as progress.uai, decisions.uai, current-state.uai, test-plan.uai, and cold-memory manifests, rather than duplicating them.

The recommended design is a versioned JSON document stored at next-recursive-prompt.uai, using a profile such as uaix.next-recursive-prompt.v1. JSON is preferable as the canonical source because UAIX’s machine-facing ecosystem is JSON-schema based, and JSON canonicalization has a published standard for repeatable hashing and signing. A human-friendly YAML rendering can exist as an optional generated mirror, but the signed, validated source of truth should remain canonical JSON.

The file should be generated or refreshed at the same moments UAIX already treats as meaningful memory transitions: after meaningful work segments, test runs, blocker changes, release-readiness changes, handoff points, intake processing, and context compaction. On restart, the loader should read the file only after the standard UAIX launch baseline and code-scoped standards files, then use it as a deterministic resume plan for the next safe loop. If the file is missing, stale, or invalid, the system should regenerate it from authoritative .uai files or fall back to a UAIX-style suspension/recovery path rather than silently proceeding with ambiguous context.

Security and integrity should combine content hashing, optional keyless signing or attestation, branch protections, and code-owner review. UAIX’s own packet schemas already require provenance and integrity fields; RFC 8785 provides canonical JSON for stable hashing; Sigstore/Cosign provides practical signing and attestation flows; and GitHub’s CODEOWNERS and protected branches provide well-understood access-control and merge-gate mechanisms for repositories.

Across the requested alternatives, a file-based repo-local approach is the best fit for the current UAIX posture because UAIX explicitly favors repo-local project memory, one shared handoff bundle, and current truth in compact hot files. A centralized store may outperform files for large fleets and cross-agent analytics, but it adds infrastructure and network dependency that the current UAIX public guidance does not make central. Embedded metadata inside existing files has the lowest object count, but it increases drift risk and makes resume logic harder to validate, diff, sign, and test independently.

UAIX Baseline and the Design Constraints It Imposes

The strongest public architectural statement UAIX currently makes is conceptual rather than implementation-specific: agent runtimes execute, and UAIX records the reviewed communication, memory, trust, evidence, and handoff boundary. The OpenAI Project Handoff guide says the runtime can handle execution, tools, handoffs, guardrails, approvals, sessions, traces, and PR workflows, while Project Handoff handles durable project memory that survives model, runtime, vendor, team, company, or session changes. This is highly relevant to your goal: preventing context loss across spin-down and restart belongs squarely in the handoff layer, not as an implicit property of runtime session state.

UAIX’s current public .uai model is also more concrete than its runtime model. The File Guide says every .uai file belongs to a declared package scope, and the current closed required-file-set model distinguishes between universal required files, profile-required files, content-triggered required files, configuration-specific required files, and out-of-scope files. As of the June 5, 2026 changelog entry, the universal launch-baseline anchors are .uai/identity.uai, .uai/world-context.uai, .uai/totem.uai, .uai/taboo.uai, and .uai/short-term-memory.uai; code-bearing packages additionally require .uai/coding-standards.uai.

UAIX also gives a clear hot-versus-cold memory split. Hot context should carry current operating truth, constraints, active routes, recent decisions, current progress, and targeted checks; long research reports, raw audits, old chats, and pre-slim snapshots should be archived into cold memory with source path, final path, checksum, actor, timestamp, summary, and disposition. That means next-recursive-prompt.uai should stay small and operational. It should not become a transcript dump, a second progress.uai, or a replacement for cold memory.

Where should .uai folders live? Public UAIX guidance is root-oriented but scope-aware. The Coding Agents guide says the supported pattern is local repository memory using AGENTS.md, .uai/readme.human, typed .uai records, and optional agent-file-handoff/ folders. The AGENTS metadata schema includes localUaiRoot and nestedScopes, and the example metadata uses .uai/ as the local root. For Visual Studio repos, UAIX specifically recommends placing .uai/ beside the real .sln or .slnx. The reviewed public record does not fully standardize per-scope nested .uai directories, but it does provide enough scope metadata to justify them in multi-root or nested-agent repositories.

The public read order is also important. UAIX’s File Guide says readers should start with AGENTS.md or .uai/readme.human when present, then read identity.uai, world-context.uai, totem.uai, taboo.uai, and short-term-memory.uai, followed by Project Handoff startup files such as startup-packet.uai, system-profile.uai, and receiver-brief.uai. The Coding Agents guide separately says that for code work, the agent must read or create .uai/coding-standards.uai before editing. This means the natural insertion point for next-recursive-prompt.uai is after baseline identity/boundary files and code standards, but before broad exploration or editing.

Two final constraints from UAIX matter for the proposed design. First, tool-specific or surface-specific files should stay thin and should not duplicate project truth. Second, linked .uai files are project context, not authority to override human requests, system instructions, repository rules, policy, or support boundaries. Therefore, next-recursive-prompt.uai should be explicitly marked as a derived operational resume file whose contents lose in any conflict with AGENTS.md, repository policy, or authoritative .uai records.

stateDiagram-v2
    [*] --> DiscoverScope
    DiscoverScope --> LoadBaseline
    LoadBaseline --> LoadCodeStandards
    LoadCodeStandards --> LoadRecursivePrompt
    LoadRecursivePrompt --> ExecuteLoop
    ExecuteLoop --> RefreshRecursivePrompt: meaningful change
    RefreshRecursivePrompt --> ExecuteLoop
    ExecuteLoop --> Suspension: spin-down / approval wait / timeout / blocker
    Suspension --> PersistAuthoritativeFiles
    PersistAuthoritativeFiles --> PersistRecursivePrompt
    PersistRecursivePrompt --> [*]
    [*] --> Resume
    Resume --> DiscoverScope

The diagram above reflects the public UAIX separation between runtime execution and durable project memory, while inserting the proposed recursive prompt file as a resumable layer for code-scoped work. The key design rule is that the authoritative files are still written first, and the recursive prompt is generated from them rather than beside them as an independent authority surface.

Recommended Architecture for next-recursive-prompt.uai

The recommended placement rule is simple: if an agent’s declared or detected scope includes code, automation, executable workflow, or code-like artifacts, require a file named next-recursive-prompt.uai in that scope’s .uai root. In a single-scope repository, that means PROJECT_ROOT/.uai/next-recursive-prompt.uai. In a nested scope with its own AGENTS.md and localUaiRoot, use SCOPE_ROOT/.uai/next-recursive-prompt.uai. If a nested code scope does not have its own .uai root, the root-scope file may temporarily serve as fallback, but it should carry a scope_id and scope_path so the loader knows it is inherited and can warn about reduced precision. This is an inference from UAIX’s localUaiRoot and nestedScopes model, not an already published UAIX requirement.

Functionally, the file should sit between short-term-memory.uai and next-actions.uai. UAIX says short-term-memory.uai carries the current compact working state, newest decisions, active blockers, and next-read pointers, while next-actions.uai lists ordered next actions with scope, owner, evidence path, acceptance condition, and blocker state. The proposed file should combine the “resume now” value of short-term memory with the “ordered next action” value of next actions, but in a tighter, executable, loop-friendly structure designed specifically for code agents resuming after loss of ephemeral runtime context.

The best mental model is: authoritative files define truth; next-recursive-prompt.uai defines the next safe loop. Its job is to answer six questions deterministically on restart: What am I trying to finish? What facts are authoritative? What changed recently? What is the next ordered sequence of steps? What checks are required before I claim success? What should I do if blocked? That pattern is consistent with Reflexion’s use of episodic verbal memory, Self-Refine’s iterative feedback-and-refinement loop, Voyager’s iterative prompting with execution feedback and self-verification, and ReAct’s interleaving of reasoning and acting.

For persistence semantics, the file should be derived hot memory, while long transcripts, rejected options, detailed logs, and bulky investigations stay in cold memory. The loader should bring in the hot set by default and only open cold-memory pointers when the task requires them. That aligns with both UAIX’s context-budget guidance and broader agent-memory literature: the agent should not try to persist everything in working context; it should checkpoint a compact, resumable state and keep long-lived memory in a slower tier.

A practical loading order for code-scoped agents is:

This order preserves UAIX’s published baseline and adds the new file as a focused resume layer rather than replacing any existing one. The ordering is a recommendation, not a published UAIX standard.

flowchart TD
    A[Authoritative .uai files] --> B[Derive compact resume state]
    B --> C[next-recursive-prompt.uai]
    C --> D[Restarted agent loads file]
    D --> E[First response summarizes truth, constraints, touchpoints, checks]
    E --> F[Ordered implementation loop]
    F --> G[Write back progress, decisions, current-state]
    G --> H[Regenerate next-recursive-prompt.uai]
    H --> I[Ready for next restart]

The flow above matches UAIX’s “write back accepted truth” rule: progress, decisions, and history are updated first; raw traces are linked or summarized; then the next startup loop is regenerated from that accepted state.

Recommended Schema and Sample Files

Because UAIX’s machine-readable ecosystem is schema-driven and JSON-first, the canonical source form should be JSON with a versioned profile name. I recommend:

• profile: uaix.next-recursive-prompt.v1
• file path: .uai/next-recursive-prompt.uai
• canonicalization: RFC 8785 JCS for hashing/signing
• status model: active | blocked | awaiting-approval | completed | stale | superseded
• authority rule: derived file; authoritative refs win on conflict

That design mirrors UAIX’s versioned profile approach for startup packets, suspension packets, receiver briefs, Project Handoff, and File Handoff, while using canonical JSON so checksums and signatures are stable across platforms.

The recommended top-level schema is below.

The field set is intentionally close to UAIX’s published packet families, which all use provenance and integrity, while also borrowing the practical focus of receiver briefs, suspension packets, and Project Handoff’s current-state/next-actions structure.

Canonical JSON sample

The sample below is proposed, not a published UAIX standard.

{
  "uai_version": "1.0",
  "profile": "uaix.next-recursive-prompt.v1",
  "schema_version": 1,
  "scope": {
    "scope_id": "payments-api",
    "scope_path": "src/PaymentsApi",
    "local_uai_root": ".uai/",
    "code_scope": true,
    "inherited_from_root": false
  },
  "lifecycle": {
    "status": "active",
    "generated_at_utc": "2026-06-10T17:42:11Z",
    "valid_until_utc": "2026-06-11T17:42:11Z",
    "attempt": 14,
    "supersedes_checksum": "sha256:3f2d0d3d3b91..."
  },
  "objective": {
    "task_id": "bugfix-payment-retry-window",
    "summary": "Fix duplicate retry scheduling in payment reconciliation without changing billing semantics.",
    "priority": "interactive",
    "done_criteria": [
      "Retry window bug is fixed in code.",
      "No billing semantics changed.",
      "Targeted tests pass.",
      "Progress and current-state files are updated."
    ]
  },
  "authoritative_refs": {
    "agents_md": "AGENTS.md",
    "readme_human": ".uai/readme.human",
    "coding_standards": ".uai/coding-standards.uai",
    "context": ".uai/context.uai",
    "constraints": ".uai/constraints.uai",
    "progress": ".uai/progress.uai",
    "decisions": ".uai/decisions.uai",
    "current_state": ".uai/current-state.uai",
    "next_actions": ".uai/next-actions.uai",
    "test_plan": ".uai/test-plan.uai",
    "stack": ".uai/stack.uai",
    "architecture": ".uai/architecture.uai"
  },
  "resume_context": {
    "current_truth_summary": [
      "The defect is isolated to duplicate enqueue behavior in reconciliation.",
      "Billing, auth, and retention behavior are out of scope.",
      "The queue adapter and reconciliation service are expected touchpoints.",
      "The authoritative verification plan is in .uai/test-plan.uai."
    ],
    "recent_changes": [
      "Added failing regression test scaffold for duplicate retry scenario.",
      "Confirmed bug reproduces when retry token expires mid-reconciliation."
    ],
    "active_blockers": [],
    "why_now": "The repo is mid-fix, and a restart should resume directly at implementation instead of re-deriving the problem."
  },
  "next_loop": {
    "mode": "implement-then-verify",
    "first_response_contract": {
      "must_report": [
        "loaded context",
        "hard constraints",
        "expected touchpoints",
        "targeted checks"
      ],
      "max_bullets": 6
    },
    "ordered_steps": [
      {
        "id": "step-1",
        "type": "inspect",
        "instruction": "Re-open the reconciliation scheduler and queue adapter paths named in architecture.uai.",
        "acceptance_checks": [
          "Confirm the exact duplicate enqueue branch before editing."
        ],
        "stop_if": [
          "The touched path conflicts with constraints.uai",
          "The defect location differs from progress.uai"
        ]
      },
      {
        "id": "step-2",
        "type": "edit",
        "instruction": "Patch duplicate retry scheduling with the smallest local change that preserves billing semantics.",
        "acceptance_checks": [
          "Change is localized.",
          "No auth, billing, or retention logic changes."
        ],
        "stop_if": [
          "A schema or contract change becomes necessary",
          "The fix requires cross-service semantics changes"
        ]
      },
      {
        "id": "step-3",
        "type": "verify",
        "instruction": "Run targeted tests from test-plan.uai plus the new regression case.",
        "acceptance_checks": [
          "Targeted tests pass",
          "Known intentionally skipped checks are reported"
        ],
        "stop_if": [
          "Required tests fail",
          "New failures indicate wider system risk"
        ]
      },
      {
        "id": "step-4",
        "type": "writeback",
        "instruction": "Update progress.uai and current-state.uai, then regenerate this file.",
        "acceptance_checks": [
          "Accepted truth is written back before final answer"
        ],
        "stop_if": [
          "Evidence path is unclear"
        ]
      }
    ],
    "if_blocked": {
      "action": "emit-blocked-state",
      "required_updates": [
        ".uai/progress.uai",
        ".uai/current-state.uai",
        ".uai/next-actions.uai"
      ],
      "human_escalation_reason_template": "State the blocker, the safe next step, and the precise approval or evidence needed."
    }
  },
  "checks": {
    "required": [
      "targeted dotnet test for reconciliation scheduler",
      "queue adapter regression test"
    ],
    "intentionally_skipped_if_not_needed": [
      "full release sweep",
      "broad smoke tests"
    ],
    "last_known_results": []
  },
  "writeback_policy": {
    "must_update_before_success": [
      ".uai/progress.uai",
      ".uai/current-state.uai"
    ],
    "update_decisions_if_changed": ".uai/decisions.uai",
    "never_copy_into_hot_files": [
      "raw traces",
      "secrets",
      "private customer data",
      "large tool logs"
    ]
  },
  "security": {
    "approval_required_for": [
      "production deploy",
      "destructive git operations",
      "schema boundary changes"
    ],
    "no_op_triggers": [
      "missing_authoritative_ref",
      "stale_constraints",
      "signature_mismatch",
      "scope_conflict"
    ],
    "escalation_triggers": [
      "billing semantics would change",
      "wider cross-service contract change is required"
    ],
    "local_policy_wins": true
  },
  "cold_memory": {
    "refs": [
      {
        "kind": "archive",
        "path": ".uai/archives/2026-06-10-payment-bug-investigation.md",
        "sha256": "sha256:9aa8f1a0...",
        "promotion_required": true
      }
    ]
  },
  "provenance": {
    "trigger": "post-test-failure-analysis",
    "generated_by": "uaix-recursive-loop-generator",
    "runtime_id": "codex-compatible-agent",
    "issued_at_utc": "2026-06-10T17:42:11Z"
  },
  "integrity": {
    "canonicalization": "RFC8785-JCS",
    "checksum": "sha256:7f3d1d42...",
    "source_digests": [
      {
        "path": ".uai/progress.uai",
        "checksum": "sha256:111..."
      },
      {
        "path": ".uai/current-state.uai",
        "checksum": "sha256:222..."
      }
    ],
    "signatures": []
  }
}

Optional YAML mirror

If a team wants a human-first rendering, it should be generated from the canonical JSON instead of being the signed source of truth.

uai_version: "1.0"
profile: "uaix.next-recursive-prompt.v1"
schema_version: 1

scope:
  scope_id: "web-frontend"
  scope_path: "src/Web"
  local_uai_root: ".uai/"
  code_scope: true

lifecycle:
  status: "awaiting-approval"
  generated_at_utc: "2026-06-10T18:03:55Z"
  attempt: 7

objective:
  task_id: "ui-cache-bust-fix"
  summary: "Complete cache-busting fix for asset manifest."
  done_criteria:
    - "Manifest generation works in CI."
    - "No deploy occurs without human approval."

resume_context:
  current_truth_summary:
    - "Build changes are localized to manifest generation."
    - "Deployment is out of scope pending approval."
  active_blockers:
    - "Need human approval before changing release pipeline."

next_loop:
  mode: "blocked"
  ordered_steps:
    - id: "step-1"
      type: "summarize"
      instruction: "Report blocker, affected paths, and the exact approval needed."
    - id: "step-2"
      type: "safe-verify"
      instruction: "Run non-deploy local checks only."

security:
  approval_required_for:
    - "release pipeline changes"
    - "production deployment"
  local_policy_wins: true

Normative schema rule: if YAML is enabled at all, it should be a read-only projection regenerated from the canonical JSON file, never the primary signed object. That recommendation follows directly from the need for deterministic canonicalization and portable checksum/signature verification.

Algorithms, Automation, and Testing

The automatic generation algorithm should treat next-recursive-prompt.uai as a derived view over authoritative handoff files. That follows UAIX’s rule that accepted truth is written back after the run, and from the broader memory literature showing that iterative agent improvement works best when feedback is turned into compact episodic memory rather than re-reading the entire trace on every retry.

Generation and refresh pseudocode

function refresh_next_recursive_prompt(scope_root):
    uai_root = resolve_local_uai_root(scope_root)

    authoritative = load_required_files(
        AGENTS.md,
        uai_root/readme.human,
        uai_root/coding-standards.uai if code_scope_detected(scope_root),
        uai_root/context.uai,
        uai_root/constraints.uai,
        uai_root/progress.uai,
        uai_root/current-state.uai if exists,
        uai_root/decisions.uai if exists,
        uai_root/next-actions.uai if exists,
        uai_root/test-plan.uai if exists,
        uai_root/stack.uai if exists,
        uai_root/architecture.uai if exists,
        uai_root/short-term-memory.uai
    )

    assert no_conflicts_with_local_policy(authoritative)
    assert code_scope_detected(scope_root) implies exists(uai_root/coding-standards.uai)

    summary = synthesize_current_truth(authoritative, max_bullets=6)
    blockers = extract_active_blockers(authoritative)
    checks = derive_targeted_checks(authoritative)
    next_steps = derive_ordered_steps(authoritative, blockers, checks)

    candidate = {
        version/profile fields,
        scope metadata,
        lifecycle metadata,
        objective,
        authoritative_refs,
        resume_context: summary + recent_changes + blockers,
        next_loop: next_steps + first_response_contract + blocked_fallback,
        checks,
        writeback_policy,
        security,
        provenance(trigger=current_event),
        integrity(source_digests=hash(authoritative))
    }

    canonical_bytes = jcs_canonicalize(candidate)
    candidate.integrity.checksum = sha256(canonical_bytes)

    if signing_enabled:
        candidate.integrity.signatures += sign(candidate)

    atomic_write(uai_root/next-recursive-prompt.uai, candidate)

Resume pseudocode

function resume_code_scoped_agent(scope_root):
    load AGENTS.md and .uai/readme.human
    load baseline anchors in published order
    load startup/system/receiver files if project handoff package
    load .uai/coding-standards.uai

    nrp = load_if_present(.uai/next-recursive-prompt.uai)

    if code_scope_detected(scope_root) and nrp is missing:
        nrp = regenerate_from_authoritative_files()

    if nrp is invalid or stale relative to progress/current-state:
        regenerate_or_fail_closed("stale next-recursive-prompt")

    verify integrity and optional signatures
    verify referenced files still exist
    verify local policy has not changed

    emit first response summary
    execute nrp.next_loop.ordered_steps until:
        success,
        blocker,
        approval wait,
        or new meaningful state transition

    write back authoritative files first
    regenerate next-recursive-prompt

The trigger model should follow UAIX’s own update cadence for hot memory. short-term-memory.uai updates after meaningful work, handoff, deployment, intake processing, or context compaction; progress.uai updates after meaningful work segments, test passes, blocker resolution, or release-preparation steps; current-state.uai updates after test runs, deployment changes, and meaningful status changes; and next-actions.uai updates on handoff, major completion, and priority/blocker changes. A good implementation therefore refreshes next-recursive-prompt.uai on the union of those events, with a short debounce to avoid writing on every token or every file save.

A recommended event policy is:

Those events are consistent with both UAIX’s hot-memory update rules and checkpoint-based persistence patterns in agent frameworks such as LangGraph, which save state snapshots at execution steps to support resumption and fault tolerance.

CI/CD hooks

For GitHub-based repositories, the CI/CD implementation is straightforward because Actions can trigger on push and pull_request with path filters, and protected branches can require passing status checks before merge. CODEOWNERS can require the appropriate maintainers to review changes to .uai/** or specifically to next-recursive-prompt.uai.

A minimal hook stack is:

A representative GitHub Actions workflow is shown below.

name: validate-next-recursive-prompt

on:
  pull_request:
    paths:
      - ".uai/**"
      - "**/AGENTS.md"
      - "**/*.cs"
      - "**/*.js"
      - "**/*.ts"
      - "**/*.py"
      - "**/*.md"
  push:
    paths:
      - ".uai/**"
      - "**/AGENTS.md"

jobs:
  recursive-prompt-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate profile and required file policy
        run: ./scripts/validate-next-recursive-prompt.sh

      - name: Verify checksum and source digests
        run: ./scripts/verify-next-recursive-prompt-integrity.sh

      - name: Ensure code scopes carry coding-standards and recursive prompt
        run: ./scripts/enforce-code-scope-required-files.sh

Integration test cases

The highest-value test suite is not unit-heavy; it is lifecycle-heavy. The file only proves its value if it survives interruption, restart, drift, and conflict reliably.

These test cases are directly aligned with UAIX’s current concern areas: current-truth drift, proof-of-use evidence, conflict between hot and cold context, network/obstruction recovery, and validator-backed proof paths.

Security, Compatibility, Costs, and Failure Recovery

Security should start with the same boundary UAIX already states elsewhere: no secrets, no automatic trust in dropped content, no authority override from context files, and local policy wins. In practice, that means next-recursive-prompt.uai must never contain raw credentials, private keys, tokens, connection strings, unreviewed sensitive logs, or private customer data; must never authorize execution on its own; and must not overrule repository policy, human instructions, or security boundaries.

For integrity, the cleanest pattern is: canonical JSON via RFC 8785, SHA-256 checksum over canonical bytes, optional Sigstore/Cosign signature or attestation over the file blob, and optional signed commits or verified commits at the repo layer. UAIX’s own machine profiles already expect integrity metadata such as algorithm, canonicalization, and checksum; JSON canonicalization is explicitly designed to make hashing and signing repeatable; Cosign is designed to sign and verify artifacts; and Cosign’s attestation support can carry structured in-toto predicates where teams want stronger provenance claims. GitHub and Git itself also support signed and verified commits, which is useful as a repository-level second line of evidence even if the file is also independently signed.

For access control, treat this file as semi-sensitive operational infrastructure. In GitHub, that means placing .uai/** or specifically **/next-recursive-prompt.uai under CODEOWNERS, requiring code-owner review for those paths, and merging only through protected branches with required status checks. If the file is especially high-risk, branch rules can also restrict who can push to protected branches and whether admins may bypass branch protections.

Backward compatibility is favorable because this can be introduced as a derived additive file. Existing agents that do not know the file can ignore it. Existing authoritative files remain authoritative. Existing repos do not need to change their conceptual model. The migration rule should therefore be: generate first, require later. This is particularly important because the current UAIX public support boundary does not claim official automatic repository writers or official CLI support; any rollout should therefore be framed as a proposed implementation improvement, not as a currently published UAIX platform capability.

A practical migration checklist is below.

• Detect code-scoped packages using the same condition UAIX already uses for coding-standards.uai.
• Add a generator that derives next-recursive-prompt.uai from authoritative files.
• Add freshness validation against progress.uai, current-state.uai, next-actions.uai, and short-term-memory.uai.
• Add a linter rule that forbids transcript dumps and large logs in the file.
• Add CODEOWNERS and required-status-check coverage for the file path.
• Add optional signing/attestation in CI for protected branches.
• Roll out as warning-only first, then enforce on PRs, then enforce on merge.
• Add cold-memory pointers for oversize resume state.
• Document precedence rules: human/system/repo policy > authoritative .uai files > next-recursive-prompt.uai.

The rollout plan should be phased:

On performance and storage, the file-based model is cheap if the context-budget rules are respected. A compact JSON resume file should usually stay in the single-digit to low tens of kilobytes range, because it should carry only current truth summaries, ordered next steps, blockers, refs, and checks—not raw traces or bulky archives. Regeneration cost is also modest because it depends on already-loaded authoritative .uai files rather than on full repository indexing every time. The main performance failure mode is not disk; it is resume-file bloat, which hot/cold splitting is specifically meant to prevent. This is a recommendation and estimate, but it directly follows UAIX’s context-budget model.

The principal failure modes are predictable. Missing file, stale file, bad references, checksum mismatch, policy conflict, overgrowth, source drift, and “loop rot” where the recursive prompt repeats obsolete instructions are the big ones. Recovery should be standardized:

• If missing, regenerate from authoritative files.
• If stale, regenerate and mark prior checksum superseded.
• If references are broken, block broad work and emit a precise blocker.
• If integrity fails, fail closed on protected branches.
• If policy conflict appears, authoritative policy and constraints win immediately.
• If hot file is too large, slim it and move detail to cold memory with provenance.
• If the runtime cannot safely continue, emit a UAIX-style blocked or suspension state with next safe step, checks run, checks skipped, blocker list, retry policy, and human escalation reason.

Developer UX should emphasize boring automation. The best experience is: the file appears automatically in code scopes, is refreshed only on meaningful transitions, has a doctor command that explains staleness or policy conflicts, and is never something contributors hand-author from scratch unless bootstrapping a new scope. A future CLI or IDE helper would be valuable, but because public UAIX materials do not currently claim official CLI/generator support, that should be communicated as a recommended implementation direction, not a current UAIX feature.

Alternatives Comparison and Final Recommendation

The table below is an analytical comparison, using UAIX’s repo-local memory guidance as the benchmark and official persistence/governance docs as the reference points. The ratings are recommendations, not existing UAIX product claims.

The file-based option wins because UAIX already centers repo-local memory, a shared front door, compact hot files, and explicit read/write-back behavior. It also matches the agent-memory literature well: a compact episodic resume artifact is closer to Reflexion-style reflection memory, Self-Refine-style iterative improvement, Voyager-style execution-feedback loops, and MemGPT-style tiered memory than either burying the loop in an existing markdown file or hiding it in infrastructure that the repo cannot easily review.

The recommended final policy is therefore:

1. Require .uai/next-recursive-prompt.uai in every code-scoped .uai root.
2. Treat it as a derived hot-memory resume artifact, never as an independent source of truth.
3. Make the canonical format JSON with profile uaix.next-recursive-prompt.v1.
4. Generate/update it on meaningful work, test, blocker, approval, compaction, and spin-down events.
5. Validate freshness against short-term-memory.uai, progress.uai, current-state.uai, and next-actions.uai.
6. Keep it compact and pointer-heavy; move bulk to cold memory with provenance.
7. Protect it with checksum, optional signature/attestation, CODEOWNERS, and protected-branch gates.
8. Roll it out in phases: shadow, warn, required, then hardened integrity.

That policy is rigorous, consistent with the current UAIX public memory model, and directly targeted at your stated risk: agents losing crucial context when they spin down and later restart.

Open Questions and Limitations

The strongest limitation is that the reviewed public UAIX record specifies the handoff and evidence model much more clearly than it specifies any underlying runtime or repository implementation. I did not find a reviewed public UAIX source repository or a published official automatic writer/CLI support claim in the materials examined, so the report’s schema, lifecycle hooks, and automation behavior are a proposed design aligned to the published model, not a description of an already-public UAIX implementation.

A second limitation is that UAIX’s current public .uai examples mix human-authored markdown/front-matter patterns with JSON-schema-based machine contracts. That is why this report recommends canonical JSON for the new file while acknowledging that some existing .uai records are human-oriented. If UAIX later publishes a stricter .uai content-format standard for local files, the canonical format recommendation here may need to be updated.

A third limitation is that alternative-agent ecosystems evolve quickly. The persistence, memory, and signing recommendations here are based on stable, primary-source design patterns from UAIX, agent-memory research, RFC 8785, Sigstore, GitHub, and LangGraph, but exact operational details for a specific UAIX runtime, IDE, or CI platform would still need adaptation by the implementer.