# Research agenda

The implementation is an engineering baseline for a future paper. It combines
explicit operator rules with bounded metadata signals to decide what to retain,
archive, delete, or review, and writes the source directory, name, purpose, and
handling recommendation to a metadata-only `workspace-artifacts/` catalog. Each
decision is inspectable and calibratable; source files stay in place by default,
while physical organization requires confirmation, or an explicit
`autonomousMode` together with `valuePolicy.organization.moveFiles`. The policy
can therefore be measured rather than treated as an opaque cleanup daemon. The
central research question is:

> How can a long-running agent keep a workspace high-information and
> human-comprehensible while preserving enough evidence for reproducibility
> and recovery?

## Candidate dimensions

### 1. Provenance and attribution

Observe file-operation tools (`write`, `edit`, shell commands) and associate
artifacts with the turn, tool call, agent, and parent task that produced them.
Compare provenance-aware selection with filename-only heuristics.

### 2. Utility and retention

Estimate an artifact's expected future utility from recency, references,
reproducibility, downstream reads, and human labels. The baseline already
uses bounded signals to make a recommendation; future policies should add
better evidence and calibrated uncertainty while keeping hard constraints and
operator overrides explicit.

### 3. Lifecycle-aware actions

Compare catalog-only updates with relocation, renaming, compression,
summarization, deduplication, and expiration. Every physical action should have
a verifiable inverse or an explicit, reviewed loss budget. For `to-delete`,
measure the ordering and reliability of source deletion and metadata-entry
removal.

### 4. Cost and information density

Measure disk bytes, model-token bytes, scan latency, prompt interruptions,
recovery time, and human task-completion accuracy. Report both raw cost and
cost per successfully completed task.

### 5. Human comprehensibility

Evaluate whether a person can answer “what happened, where is the evidence,
and how do I undo this?” from the workspace, catalog, and manifest. Candidate
metrics include search time, path predictability, catalog completeness, and
reviewer agreement.

## Suggested benchmark protocol

1. Build a corpus of long-running coding, data, and simulation tasks with
   reproducible seeds and recorded file events.
2. Randomize tasks to unmanaged, heuristic-managed, and provenance-managed
   conditions.
3. Hold model, tools, and task budget constant; vary only maintenance policy.
4. Pre-register safety failures (wrong-file move, source loss, path escape) as
   hard-stop outcomes.
5. Measure token/disk growth and final task quality at fixed checkpoints.
6. Ask blinded reviewers to locate evidence and restore a selected artifact.

## Hypotheses worth testing

- H1: A bounded plan/apply protocol reduces workspace bytes and prompt noise
  without lowering task success.
- H2: Provenance signals improve precision more than adding filename rules.
- H3: Human confirmation is most useful when the plan explains reasons,
  confidence, and exact reversible destinations.
- H4: A metadata catalog plus an external, append-only manifest reduces recovery
  time compared with an in-workspace log that is itself buried by artifacts.
- H5: Under the same value policy, autonomous mode lowers maintenance
  interaction cost but requires stricter boundary and rollback evaluation.

## Current baseline and non-goals

This repository currently provides the baseline needed to run those
experiments: managed roots, protected paths, bounded deterministic scanning,
value classification, action decisions, metadata-catalog synchronization,
organization/name suggestions, hash-bound plans, quarantine, restore, and
compact results. Manual mode does not move or delete source files by default;
autonomous mode is an explicit experiment switch and remains bounded by hard
protections, budgets, fingerprints, and delete permission. The project does not
yet learn policies, inspect semantic references, or summarize content.