prometeu-studio/docs/packer/decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md

Diagnostics, Doctor, Quarantine, and Workspace Hygiene Decision

Status

Accepted

Date

2026-03-11

Context

This decision closes the architectural questions raised in 01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.

The packer is expected to operate as a sanity guardian over a potentially messy assets/ workspace while still preserving trust and predictability.

This means the packer must:

• protect the correctness of managed builds;
• surface hygiene problems in the broader workspace;
• avoid surprising destructive or reorganizing mutations;
• keep recovery and auditability stronger than convenience heuristics.

Decision

The packer adopts a validate-the-managed-world, inspect-the-workspace, mutate-only-with-consent model.

1. Diagnostic classes

Diagnostics are divided into two major classes:

• build-blocking structural errors;
• advisory workspace hygiene diagnostics.

Build-blocking structural errors include, at minimum:

• registered asset root missing its anchor asset.json;
• invalid asset.json;
• missing required inputs for a managed asset;
• output contract inconsistency;
• invalid preload-related artifact state;
• structural identity collisions or ambiguous ownership.

Advisory workspace hygiene diagnostics include, at minimum:

• orphan asset.json declarations;
• duplicate source content by hash;
• large unused files;
• assets not currently referenced by managed build inputs;
• naming or organization hints.

2. Registry validation versus workspace scanning

Registry validation and workspace scanning are distinct surfaces.

Rules:

• build-time validation is scoped to the managed world defined by the registry;
• workspace scanning is a broader hygiene pass over assets/;
• doctor without wider scope flags validates the managed world;
• doctor --workspace expands visibility to broader workspace chaos.

The build must not silently turn into a full workspace scanner.

3. Safety model for automatic fixes

Automatic fixes are allowed only for corrections that are mechanical, deterministic, and safe.

Safe automatic fixes include:

• path normalization;
• explicit materialization of already-determined defaults;
• canonical ordering or formatting of declaration data;
• strictly mechanical regeneration of control-file content when explicitly requested.

Unsafe automatic fixes are not baseline-safe:

• moving user content;
• deleting user content;
• deduplicating content by rewriting authoring files;
• renaming assets;
• auto-registering or auto-adopting assets without explicit consent.

4. Explicit consent policy

Any operation that mutates user-controlled workspace content requires explicit consent.

This includes:

• quarantine moves;
• deletion;
• adoption/registration of previously unmanaged assets;
• changes in physical file location;
• changes that alter declared authoring intent rather than only normalizing control data.

5. Quarantine model

Quarantine is a reversible staging area, not a magic trash bin.

Rules:

• quarantine is never automatic by default;
• the packer must explain what is being moved and why;
• recovery must remain possible;
• quarantine exists to support explicit hygiene workflows, not hidden cleanup.

6. Detection aggressiveness

The packer should be aggressive in detection and conservative in action.

Meaning:

• detect broadly when scanning workspace hygiene;
• report clearly and specifically;
• avoid mutating content unless the action is explicitly requested and safe.

7. doctor --fix

doctor --fix is limited to safe mechanical corrections in the baseline contract.

Rules:

• it must not mutate authoring content as a baseline behavior;
• it must not move or delete content without a stronger explicit operation;
• it must remain predictable enough that users can trust it in Studio and CLI-adapter workflows.

8. Structural conflicts

Conflicts between registry state, anchor files, and managed identity are structural errors.

Examples:

• two asset roots competing for the same identity;
• registered root without anchor;
• duplicated or ambiguous anchor declarations under managed expectations.

These are not advisory hygiene warnings. They invalidate the managed build contract.

9. Duplicate content policy

Duplicate source content by hash is not a structural build error in the baseline contract.

Rules:

• it is a hygiene warning or hint;
• it may inform cost, cleanup, or optimization workflows;
• it does not imply semantic invalidity by itself.

10. Orphan asset policy

Orphan asset.json declarations do not block the baseline build.

Rules:

• they belong to workspace hygiene surfaces;
• they should be visible in doctor --workspace;
• they do not become managed assets automatically;
• stricter policy can be added later, but it is not part of the current baseline.

Invariants and Constraints

The following invariants now apply:

1. The build validates the managed registry-defined world, not the entire workspace by default.
2. Workspace hygiene scanning is broader than build validation.
3. Structural managed-world errors block builds.
4. Hygiene findings do not block builds by default unless separately elevated by policy.
5. doctor --fix is limited to safe mechanical corrections.
6. Quarantine is explicit and reversible.
7. Destructive or relocational mutations require explicit consent.
8. Duplicate content is advisory, not structurally invalid by itself.
9. Orphan anchors are diagnosable, not build-active.
10. Trust and reversibility are preferred over aggressive automatic remediation.

Explicit Non-Decisions

This decision does not yet define:

• the full taxonomy and numbering of diagnostic codes;
• richer policy knobs such as strict workspace modes by profile;
• detailed UI presentation in Studio;
• watch-mode-specific hygiene behavior;
• detailed garbage collection flows beyond the baseline safety model.

Those belong to later decisions and specs.

Propagation Targets

This decision must propagate to:

• packer diagnostics contract spec;
• doctor and workspace scanning spec;
• quarantine and garbage collection spec;
• Studio service behavior for inspection, fix, and cleanup actions;
• future implementation of safe fix classification and explicit-consent workflows.

Validation Notes

Example: orphan anchor

• assets/wip/new_bank/asset.json exists
• it is not registered in the managed registry
• build does not fail by default
• doctor --workspace must surface it

Example: unsafe fix

• two large duplicate PNGs are detected in workspace
• packer may report them
• packer must not delete or move either file automatically in baseline behavior

Example: structural error

• a registered asset root no longer contains its anchor asset.json
• this is a managed-world integrity failure
• build validation must fail