file · Command reference
qzx auditWorkspace
What it does
Builds a deterministic, fingerprinted workspace cleanup plan without altering workspace contents
Command maturity: Alpha
Available for real use and feedback while its interface and behavior can still evolve. This is the current development-checkout assessment. Every future immutable release tag preserves the exact assessment shipped by that version. Available in PyPI 0.2.2.0.9. This page documents the 0.2.2.0.9 alpha development checkout.
Behavior and built-in protections
Live mode applies the changes you request
Direct execution for this operation
Works without invoking native programs
Works without network access
No elevation required by design
The audit never changes workspace contents. By default it is fully read-only; plan_file may explicitly create one new content-addressed JSON plan and never overwrites an existing file. Artifacts, logs, backups, filename patterns, links, special entries, and reorganization suggestions remain review-only.
This safety classification was reviewed by OpenAI GPT-5.6 Sol against implementation digest sha256:c9c12a87a4e34c402974dda6d9cdbe06600092b5fa10f36ff9936a05e4aca237 on 2026-09-05.
Exact syntax
qzx auditWorkspace [path] [categories] [max_files] [plan_file] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| path | str | No | "." | Workspace directory to audit |
| categories | str | No | "build,temp,artifacts,duplicates,reorganizations" | Comma-separated categories: build, temp, artifacts, duplicates, reorganizations |
| max_files | int | No | 15000 | Maximum number of non-directory entries to inspect |
| plan_file | str | No | Not declared | Optional new JSON file in which to save the plan; existing files are never overwritten |
Input examples
qzx auditWorkspace .Inspect the current workspace without writing files
qzx auditWorkspace . --categories build,temp,duplicates --plan-file qzx-repair-plan.jsonSave a plan that repairWorkspace can validate later
For the complete structured payload, add --json: qzx auditWorkspace [path] [categories] [max_files] [plan_file] --json
Observed output example
Captured with QZX 0.2.2.0.9 on Windows 11; exit code 0. Host-dependent values and duration can vary.
Example command: qzx auditWorkspace ../artifacts/qzx-evidence/repair-workspace/workspace --plan-file ../artifacts/qzx-evidence/repair-workspace/plan.json --json
{
"success": true,
"status": "complete",
"message": "Workspace audit complete: 1 executable cleanup action(s) and 0 review-only finding(s), totaling 28 recoverable byte(s). Plan saved to 'C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\repair-workspace\\plan.json'.",
"details": {
"path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\repair-workspace\\workspace",
"workspace_unchanged": true,
"plan_file": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\repair-workspace\\plan.json",
"plan": {
"schema_version": 1,
"root": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\repair-workspace\\workspace",
"categories": [
"build",
"temp",
"artifacts",
"duplicates",
"reorganizations"
],
"max_files": 15000,
"scan_complete": true,
"scanned_files": 1,
"scanned_directories": 0,
"ignored_paths": [],
"scan_errors": [],
"actions": [
{
"category": "temp",
"kind": "delete_file",
"path": "debug.tmp",
"reason": "Temporary editor or tool output selected for explicit cleanup.",
"executable": true,
"size_bytes": 28,
"fingerprint": {
"type": "file",
"size_bytes": 28,
"sha256": "a4be5b5eeff332365000a7d71223443e63df5d51a58fdb60aa682b8b01d22266"
},
"id": "act-76685ad35f1fd085e962"
}
],
"summary": {
"total_actions": 1,
"executable_actions": 1,
"review_only_actions": 0,
"recoverable_bytes": 28,
"category_counts": {
"build": 0,
"temp": 1,
"artifacts": 0,
"duplicates": 0,
"reorganizations": 0
}
},
"plan_id": "plan-70b0f1e9ef689794bc9423b4e17812fad340a3316bb5ddf912c29483aa6d05b5"
}
},
"meta": {
"command": "auditWorkspace",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 31.418,
"schema_version": 1
}
}View the JSON result contract
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"success",
"message",
"meta"
],
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"meta": {
"type": "object",
"required": [
"command",
"command_maturity",
"duration_ms",
"schema_version"
],
"properties": {
"command": {
"type": "string"
},
"command_maturity": {
"type": "object",
"required": [
"stage",
"label",
"sequence",
"public_executable",
"stability",
"summary",
"promotion_review_required",
"assessment_scope"
],
"properties": {
"stage": {
"type": "string"
},
"label": {
"type": "string"
},
"sequence": {
"type": "integer"
},
"public_executable": {
"type": "boolean"
},
"stability": {
"type": "string"
},
"summary": {
"type": "string"
},
"promotion_review_required": {
"type": "boolean"
},
"assessment_scope": {
"type": "string"
},
"note": {
"type": "string"
},
"review": {
"type": "object",
"required": [
"reviewed_on",
"rationale",
"evidence"
],
"properties": {
"reviewed_on": {
"type": "string",
"format": "date"
},
"rationale": {
"type": "string"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"replacement": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"duration_ms": {
"type": "number"
},
"schema_version": {
"type": "integer"
}
},
"additionalProperties": true
},
"details": {
"oneOf": [
{
"type": "object",
"properties": {
"path": [],
"workspace_unchanged": {
"type": "boolean"
},
"plan_file": [],
"plan": []
},
"additionalProperties": true
},
{
"type": "object",
"properties": {
"path": []
},
"additionalProperties": true
},
{
"type": "object",
"properties": {
"path": [],
"plan": [],
"plan_file": []
},
"additionalProperties": true
}
]
},
"error": [],
"error_code": {
"type": "string"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}Errors and limits
The public contract requires success=false and a descriptive message on failure. This catalog does not yet declare a command-specific error taxonomy; inspect the result and do not invent error codes.
QZX is alpha software. Optional dependencies, permissions, and host capabilities can change the result.
Evidence workflow: captured and digest-validated.
Evidence and provenance
- Implementation
- src/qzx/commands/file/audit_workspace.py
- Tests
- No command-specific test file with the same module name was found; this does not prove that all coverage is absent.
- Documentation channel
- Development documentation 0.2.2.0.9 · main · sha256:cfba936e39931c286ca23add0ae546693db17d8b316e7cbc3891d26642d9b7e8
- Availability
- 0.2.2.0.9 or earlier
Keep exploring
Related commands
These commands also belong to the file category. Compare them to choose the operation that best fits your task.
qzx touchFileCreates an empty file or updates the timestamp of an existing fileqzx calculateFileHashCalculates cryptographic hashes (MD5, SHA-1, SHA-256) of a fileqzx repairWorkspaceValidates a saved auditWorkspace plan and applies only explicitly selected, unchanged cleanup actionsqzx changePermissionsChanges permissions of a file or directory