Covers 8 major scenario categories and 28 sub-scenarios (explicit/implicit contradictions, invalidation and aging, metadata quality, Maestro specialization, timeline artifacts T1-T6, knowhow drift, artifact residue); see workflow knowledge-audit.md for definitions.
Closed loop: harvest writes → audit reviews → three-state elimination; complementary to harvest --prune(physical GC): audit performs semantic-layer judgment, and before deleting unextracted artifacts it reversely triggers harvest rescue.
<required_reading> @~/.maestro/workflows/knowledge-audit.md </required_reading>
<deferred_reading>
- @~/.maestro/workflows/harvest.md (the artifacts detected by audit are the product source of harvest)
- @~/.maestro/workflows/specs-add.md (the
<spec-entry>variant required for the deprecate operation) </deferred_reading>
Scope (required): spec | knowhow | artifact | all
Deletion strategyDefault --interactive(item-by-item decision via three-state panel); non-interactive mode --mark(mark only) / --delete(soft delete to .trash/）/ --purge(physical erasure, artifacts only and requires double confirmation).
The full flag set, scan paths corresponding to scope, Stage steps, and detection algorithm definitions are in workflow knowledge-audit.md.
Key invariants:
- Backup before mutate — Stage 6 must package the files to be changed into
.workflow/.trash/knowledge-audit-{timestamp}/; if backup fails, Stage 7 is prohibited. - Deprecate over delete — For text storage (spec/knowhow), prefer injecting
status="deprecated"to preserve history; only physical artifact residue goes through delete/purge. - Purge requires double confirmation —
--purgeapplies only to artifact scope, and Stage 5 must explicitly require[y/N]secondary confirmation + entering the artifact id. - Rescue before delete — Before deleting an unextracted artifact (
harvest-log.jsonlno record), forcibly prompt "whether to first/manage-harvest？"。
Scope paths, the 8 detection algorithm categories, the three-state decision panel, and the report schema are defined in workflow knowledge-audit.md.
Next-step routing on completion:
- Review elimination records →
.workflow/.knowledge-audit/audit-report-{date}.md - rescue unextracted artifacts →
/manage-harvest <artifact-id> - verify current spec state →
/spec-load --role implement - periodic inspection → run at the end of each milestone
--scope all --report
<error_codes>
| Code | Severity | Condition | Recovery |
|---|---|---|---|
| E001 | error | .workflow/ not initialized |
run first /maestro-init |
| E002 | error | --scope missing or invalid |
provide spec/knowhow/artifact/all |
| E003 | error | --purge and --dry-run used together |
choose one of the two |
| E004 | error | --purge acts on non-artifact scope |
purge only supports artifact scope |
| E005 | error | Backup failed (.trash/ write exception) |
check disk space and permissions, then retry |
| W001 | warning | conflict detected but user chooses keep | record in report, do not block |
| W002 | warning | artifact to be deleted has no harvest-log record | prompt to run manage-harvest first |
| W003 | warning | cyclic supersedes chain | automatically break the cycle or interactively select the node to keep |
| W004 | warning | detection takes >120s (large-scale spec library) | suggest adding --scope to converge or --since incremental |
| W005 | warning | LLM detector unavailable | degrade to the regex + graph algorithm subset, skipping category B/G semantic scenarios |
| </error_codes> |
<success_criteria>
- Scope parses correctly, mutually exclusive flag validation passes
- The three stores are loaded by scope, building a unified finding pool
- Stage 3 timeline index established (mtime ↔ session/milestone state)
- Stage 4 outputs the finding list by P0/P1/P2
- If not
--report: the user makes a three-state decision for each item - Rescue confirmation is triggered before deleting an unharvested artifact
- Stage 6 backup tarball generated at
.workflow/.trash/ -
deprecateCompleted via metadata injection (spec/knowhow files were not physically deleted) -
deleteMoved to.trash/, index synchronized and updated -
purgeExecuted only after dual confirmation passes -
audit-report-{date}.md+audit-log.jsonlWrite completed - The summary displays the three-storage change counts and the next-step routing </success_criteria>