Praetor File System Steward

> Status: active product direction, staged implementation. ADR-002 restores

> File System Steward as a core Agent in the Praetor company. The Agent should

> exist in the organization model and UI as the owner of workspace hygiene,

> naming, placement, and archiving recommendations.

>

> The large registry/restructure implementation described below is still

> deferred. Do not reintroduce heavy file registry tables or automatic

> restructure plans until there is a chairman-visible workflow that reads and

> benefits from them.

Deferred registry layer

> The first implementation of this layer (file_assets,

> file_moves, workspace_reconciliation_reports, workspace_restructure_plans,

> the WorkspaceMixin in service_workspace.py, and 6 API routes under

> /api/workspace/*) was removed from the codebase in May 2026 because it was

> wired into every mission creation but never used through any owner-facing

> flow. Keeping ~1,600 LoC and 4 SQLite tables to seed placeholder records was

> inflating the data model and slowing down the rest of the refactor.

>

> The registry design below survives as a later implementation path, once the

> lightweight File System Steward experience is useful and there is real user

> signal demanding a stable-identity file registry.

>

> When this work resumes, the right path is:

>

> 1. Start from a real user pain (e.g. "I reorganised my workspace and now the

> Wiki has dead links"), not from a speculative schema.

> 2. Reuse the mission_jobs worker queue rather than a new background loop.

> 3. Build the read-only reconciliation report first (lowest blast radius),

> only add restructure plans once the report has been validated against a

> real workspace.

> 4. Treat the file registry as a derivable index over the workspace, not a

> source of truth — the workspace itself is the source of truth (see

> PRAETOR_PRODUCT_BRIEF §8.1).

---

Core Agent Responsibilities

The File System Steward Agent is responsible for:

• keeping all Praetor company files inside the configured workspace root
• naming mission, project, meeting, decision, and artifact files consistently
• recommending where files should be placed
• preparing archive recommendations
• producing workspace hygiene reports
• noticing missing or confusing files
• helping users understand where outputs live

Current Lightweight Surface

Praetor now exposes a lightweight File System Steward index before any heavy

registry layer:

• GET /api/workspace browses the real workspace folder.
• GET /api/workspace/file previews Markdown, JSON, and text files and shows

the visible absolute host path.

• GET /api/workspace/hygiene returns conservative recommendations for missing

roots, misplaced files, archive candidates, path naming issues, and broken

meeting file links.

• GET /api/workspace/steward returns the company file operating picture:

expected root folders, recent work products, meeting files, decision files,

the steward contract, and hygiene summary.

The Workspace UI uses this index as an operating panel, not a hidden registry.

The local workspace remains the source of truth.

The File System Steward must not:

• silently move sensitive files
• silently overwrite user-created files
• treat an internal registry as the source of truth
• hide company work products in app-internal storage

Principle

The chairman should not need to design folders, rename files, or keep document

links synchronized by hand. Praetor should do that as company operations work.

Filesystem paths are locations, not identity.

Durable references should point to stable records:

• file_asset_id
• document_id
• document_version_id
• matter_id
• mission_id

This allows Praetor to reorganize folders while preserving Wiki links, document

registry records, and agent references.

File intake

Every file source should enter the same stewardship flow:

1. User upload

2. AI-generated document

3. Downloaded file

4. Runtime output

5. Requested mission output

6. Manually discovered workspace file

Praetor would register each as FileAssetRecord with:

• current path
• previous paths
• source
• sensitivity
• purpose
• client / matter / mission links
• document / version links when relevant
• steward notes

The workspace would also receive .praetor/file_manifest.json as a

machine-readable index.

Restructure plan

Praetor should not silently perform risky folder moves.

WorkspaceRestructurePlan would record:

• proposed moves
• why the moves are useful
• Wiki updates needed
• registry updates needed
• risks
• whether approval is required

Low-risk internal organization can later be automated. Client, legal, privacy,

delivery, credential, or high-volume restructuring should require review.

Reconciliation

Praetor must assume that users and external tools can modify the workspace

without going through the CEO.

Workspace reconciliation would compare a registry with the filesystem and Git:

• tracked file still exists
• tracked file is missing
• tracked file content changed
• tracked file appears to have moved
• filesystem file is untracked
• Git reports modified, deleted, renamed, or untracked files

Reconciliation must be conservative. It should create a report and update asset

fingerprints, but it must not overwrite user changes or silently move sensitive

files.

Each registered file would store:

• size
• modified time
• SHA-256
• last seen time
• existence state
• sync status

If a missing asset has the same hash at a new path, Praetor would treat it as a

moved candidate and ask for registry confirmation.

What was tried in v1

The first pass registered three intake sources:

• mission requested outputs
• planned document versions
• runtime changed files

and exposed read endpoints (/api/workspace/steward,

/api/missions/{id}/workspace-steward), reconciliation endpoints

(/api/workspace/reconcile, /api/missions/{id}/workspace-reconcile), and

restructure-plan endpoints (/api/workspace/restructure-plan,

/api/missions/{id}/workspace-restructure-plan).

It seeded placeholder records on every mission creation, which made the

mission-create path slower and the schema fatter without delivering any

chairman-visible value. None of the read endpoints were called from a

production user flow. Removing the layer cut ~1,600 lines and freed up four

SQLite tables.

When this resumes, the bar is: **no schema row gets written unless a

chairman-visible affordance reads from it.**