file · Command reference

`qzx auditWorkspace`

What it does

Builds a deterministic, fingerprinted workspace cleanup plan without altering workspace contents

Canonical command: auditWorkspace

Accepted aliases: None

Case-sensitive: no

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.6a8. This page documents the 0.2.2.0.6a8 alpha development checkout.

Safety and effects

Can mutate state

No documented dry-run parameter

No native program invocation in the current classification

No documented network use

No inherent elevation requirement

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 Codex against implementation digest sha256:d13f31382827b9e0607aca8655635394a118b5cf1b481f01b03722b84ddda4ae on 2026-07-30.

Exact syntax

qzx auditWorkspace [path] [categories] [max_files] [plan_file] --json

Parameters

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.json

Save a plan that repairWorkspace can validate later

For the complete structured payload, add --json: qzx auditWorkspace [path] [categories] [max_files] [plan_file] --json

Representative output example

This illustrative JSON is derived from the current implementation-backed result contract. It shows what the command can return without claiming a recorded execution; values vary with inputs, host, permissions, and optional tools.

Example command: qzx auditWorkspace . --json

{
    "success": true,
    "message": "Builds a deterministic, fingerprinted workspace cleanup plan without altering workspace contents. In this illustrative example, the command completed successfully.",
    "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": 0,
        "schema_version": 1
    },
    "details": {
        "path": "C:\\project\\example.txt",
        "workspace_unchanged": true,
        "plan_file": "C:\\project\\example.txt",
        "plan": "Example value"
    },
    "status": "ok"
}

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: requires an isolated disposable target.

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.6a8 · main · sha256:040df8bbcb6b707bb4cdb7c2c1ad4cc6956ab647a451dc215ea78cdbb4c8ad96
Availability: 0.2.2.0.6a8 or earlier

Keep exploring

These commands also belong to the file category. Compare them to choose the operation that best fits your task.

Explore all QZX commands