Closed-loop: harvest extracts → stores → downstream consumers (wiki-digest, spec-load, maestro-plan --gaps).
<required_reading> @~/.maestro/workflows/harvest.md </required_reading>
Modes:
- No args →
scan: discover all harvestable artifacts, interactive selection <session-id>→session: harvest specific session<path>→path: harvest from explicit directory
Flags:
--to <target>— Force routing: wiki, spec, issue, auto (default: auto)--source <type>— Filter: analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, session, learning, all--recent N— Artifacts within last N days (default: 30)--dry-run— Preview without writing-y— Skip confirmations--min-confidence N— Minimum 0.0-1.0 (default: 0.5)--prune— State hygiene mode: classify artifacts, graduate harvested → knowhow, archive from state.json, prune accumulated_context--age N— Graduation age threshold in days (default: 14). Used with--prune
Output boundary: ALL file writes MUST target .workflow/knowhow/, .workflow/specs/, .workflow/issues/, .workflow/wiki/, .workflow/harvest/, or .workflow/state.json only. NEVER modify source code, source artifacts, or files outside these paths.
Source registry:
| Source | Scan Path | Key Files |
|---|---|---|
| analysis | .workflow/.analysis/ANL-*/ |
conclusions.json |
| brainstorm | .workflow/scratch/brainstorm-*/ |
guidance-specification.md |
| lite-plan | .workflow/.lite-plan/*/ |
plan.json |
| lite-fix | .workflow/.lite-fix/*/ |
fix-plan.json |
| debug | .workflow/.debug/*/ |
debug-log.md |
| scratchpad | .workflow/.scratchpad/ |
*.md |
| session | .workflow/active/WFS-*/ |
workflow-session.json |
| learning | .workflow/specs/ |
learnings.md |
Phase Gates (MANDATORY, BLOCKING)
GATE 1: Discovery → Extraction (Stages 1-3 → Stage 4)
- REQUIRED: Source artifacts discovered and mode resolved (scan/session/path).
- REQUIRED: User selected artifact(s) to harvest (or auto-selected via session/path mode, or
-y). - BLOCKED if no harvestable artifacts found (W001) or invalid source (E004/E005).
GATE 2: Extraction → Routing (Stage 4 → Stage 5-6)
- REQUIRED: All files in selected artifacts loaded and parsed.
- REQUIRED: Knowledge fragments extracted with category, confidence, and tags.
- REQUIRED: Fragments filtered by
--min-confidence. - BLOCKED if extraction produces zero fragments.
GATE 3: Routing → Write (Stage 6 → Stage 7-8)
- REQUIRED: Routing classification applied (auto or forced by
--to). - REQUIRED: Dedup check passed against harvest-log.jsonl and existing stores.
- REQUIRED: If
--dry-run: preview displayed, no files written — GATE blocks further writes. - BLOCKED if dedup check fails or store paths unresolvable.
Routing rules:
- Universal design patterns →
codingorarchcategory - Component-level pitfalls →
learningcategory - Quality enforcement rules →
qualitycategory - Wiki:
maestro wiki create --type <type> --slug harvest-<source_type>-<short_id> - Spec:
$spec-add "<category> <content>"(single source of truth — always use spec-add for spec routing; do NOT usemaestro wiki appendfor spec entries) - Issue: append to
issues.jsonlmatching canonical schema, withsource: "harvest"field (distinguishes frommanage-issue-discover, which usessource: "discover"— required for cross-skill dedup when both write concurrently)
Next steps: $manage-wiki health, maestro search --type note, $wiki-connect --fix, $wiki-digest, $manage-issue list --source harvest, $manage-knowledge-audit --scope spec (when specs extracted, check for conflicts)
Prune mode (--prune): Classifies artifacts (active/graduated/stale/protected), graduates harvested artifacts to wiki knowhow, archives from artifacts[] → artifact_archive[], prunes resolved entries from accumulated_context. Files on disk are never deleted. Always backs up state.json before writing.
<error_codes>
| Code | Severity | Condition | Recovery |
|---|---|---|---|
| E001 | error | .workflow/ not initialized | Run $maestro-init |
| E002 | error | Invalid --to target | Valid: wiki, spec, issue, auto |
| E003 | error | Invalid --source type | Display valid types |
| E004 | error | Session ID not found | Show available sessions |
| W001 | warning | No harvestable artifacts in window | Widen --recent |
| W003 | warning | Fragments below threshold | Lower --min-confidence |
| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl |
| </error_codes> |
<success_criteria>
- Mode resolved (scan / session / path)
- Artifacts discovered and parsed
- Fragments extracted with category, confidence, tags
- Dedup check passed against harvest-log.jsonl and stores
- If not dry-run: routed items written to target stores
- harvest-log.jsonl updated with provenance
- harvest-report-{date}.md written
- No source artifacts modified
- If --prune: artifacts classified (active/graduated/stale/protected)
- If --prune: graduated artifacts → knowhow + artifact_archive[]
- If --prune: accumulated_context pruned (resolved deferred/blockers, deduplicated decisions)
- If --prune: state.json backed up before modification </success_criteria>