plcode-linux-arm64-musl 2.1.0

package/.plcode/context/core/context-system/operations/harvest.md

@@ -0,0 +1,310 @@
+# Context Harvest Operation
+
+**Purpose**: Extract knowledge from AI summaries → permanent context, then clean workspace
+
+**Last Updated**: 2026-01-06
+
+---
+
+## Core Problem
+
+AI agents create summary files (OVERVIEW.md, SESSION-\*.md, SUMMARY.md) that contain valuable knowledge but clutter the workspace. These files "plague" the codebase.
+
+**Solution**: Harvest the knowledge → permanent context, then delete the summaries.
+
+---
+
+## Auto-Detection Patterns
+
+<rule id="summary_patterns" enforcement="strict">
+  Harvest automatically detects these patterns:
+  
+  Filename patterns:
+  - *OVERVIEW.md
+  - *SUMMARY.md
+  - SESSION-*.md
+  - CONTEXT-*.md
+  - *NOTES.md
+  
+  Location patterns:
+  - Files in .tmp/ directory
+  - Files with "Summary", "Overview", "Session" in title
+  - Files >2KB in root directory (likely summaries)
+</rule>
+
+---
+
+## 6-Stage Workflow
+
+<workflow id="harvest" enforce="@critical_rules">
+  
+### Stage 1: Scan
+**Action**: Find all summary files in workspace
+
+**Process**:
+
+1. Search for auto-detection patterns
+2. Check .tmp/ directory
+3. List files with sizes
+4. Sort by modification date (newest first)
+
+**Output**: List of candidate files
+
+**Example**:
+
+```
+Found 3 summary documents:
+1. CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB, modified 1 hour ago)
+2. SESSION-auth-work.md (1.8 KB, modified today)
+3. .tmp/IMPLEMENTATION-NOTES.md (800 bytes, modified today)
+```
+
+---
+
+### Stage 2: Analyze
+
+**Action**: Categorize content by function
+
+**Mapping Rules**:
+| Content Type | Target Folder | How to Identify |
+|--------------|---------------|-----------------|
+| Design decisions | `concepts/` | "We decided to...", "Architecture", "Pattern" |
+| Solutions/patterns | `examples/` | Code snippets, "Here's how we..." |
+| Workflows | `guides/` | Numbered steps, "How to...", "Setup" |
+| Errors encountered | `errors/` | Error messages, "Fixed issue", "Gotcha" |
+| Reference data | `lookup/` | Tables, lists, paths, commands |
+
+**Process**:
+
+1. Read each file
+2. Identify valuable sections (skip planning/conversation)
+3. Categorize by function
+4. Determine target file path
+5. Generate preview (first 60 chars)
+
+**Output**: Categorized items with letter IDs
+
+---
+
+### Stage 3: Approve (CRITICAL)
+
+**Action**: Present approval UI with letter-based selection
+
+<rule id="approval_gate" enforcement="strict">
+  ALWAYS show approval UI before extracting/deleting.
+  NEVER auto-harvest without user confirmation.
+</rule>
+
+**Format**:
+
+```
+### CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)
+
+✓ [A] Design: Function-based context organization
+    → Would add to: core/concepts/context-organization.md
+    Preview: "Organize by function (concepts/, examples/...)..."
+
+✓ [B] Pattern: Minimal Viable Information
+    → Would add to: core/concepts/mvi-principle.md
+    Preview: "Extract core only (1-3 sentences), 3-5 key points..."
+
+✓ [C] Workflow: Harvesting summary documents
+    → Would create: core/guides/harvesting.md
+    Preview: "Scan for summaries → Extract → Approve → Delete"
+
+✗ [D] Skip: Planning discussion notes (temporary knowledge)
+
+---
+
+### SESSION-auth-work.md (1.8 KB)
+
+✓ [E] Error: JWT token expiration not handled
+    → Would add to: development/errors/auth-errors.md
+    Preview: "Symptom: 401 after 1 hour. Cause: No refresh flow..."
+
+✓ [F] Example: JWT refresh token implementation
+    → Would create: development/examples/jwt-refresh.md
+    Preview: "Store refresh token → Check expiry → Request new..."
+
+---
+
+### .tmp/IMPLEMENTATION-NOTES.md (800 bytes)
+
+✗ [G] Skip: Duplicate info (already in development/concepts/api-design.md)
+
+---
+
+**Quick options**:
+- Type 'A B C E F' - Approve specific items
+- Type 'all' - Approve all ✓ items (A B C E F)
+- Type 'none' - Skip harvesting, delete files anyway
+- Type 'cancel' - Keep files, don't harvest
+```
+
+**Validation**:
+
+- MUST wait for user input
+- MUST not proceed without approval
+- If user types 'cancel', stop immediately
+
+**Output**: List of approved items
+
+---
+
+### Stage 4: Extract
+
+**Action**: Extract and minimize approved items
+
+<rule id="extraction" enforce="@mvi_principle">
+  Apply MVI to all extracted content:
+  - Core concept: 1-3 sentences
+  - Key points: 3-5 bullets
+  - Minimal example: <10 lines
+  - Reference link: to original source
+  - Files: <200 lines each
+</rule>
+
+**Process**:
+
+1. For each approved item:
+   - Extract core content
+   - Apply MVI minimization (see compact.md)
+   - Add to target file (create if needed)
+   - Add cross-references
+   - Update related files
+2. Update navigation.md navigation maps
+3. Validate file sizes (<200 lines)
+
+**Output**: List of created/updated files
+
+---
+
+### Stage 5: Cleanup
+
+**Action**: Archive or delete source summary files
+
+**Default Strategy**: Archive (safe)
+
+- Move to `.tmp/archive/harvested/{date}/`
+- Preserves originals in case of mistakes
+- Can be safely deleted later
+
+**Alternative**: Delete (if user specified)
+
+- Permanently remove files
+- Only delete items user approved for harvest
+
+<rule id="cleanup_safety" enforcement="strict">
+  ONLY cleanup files that had content successfully harvested.
+  If extraction failed, keep the original file.
+</rule>
+
+**Output**: Cleanup report
+
+---
+
+### Stage 6: Report
+
+**Action**: Show comprehensive results summary
+
+**Format**:
+
+```
+✅ Harvested 5 items into permanent context:
+   - Added to core/concepts/context-organization.md
+   - Added to core/concepts/mvi-principle.md
+   - Created core/guides/harvesting.md
+   - Added to development/errors/auth-errors.md
+   - Created development/examples/jwt-refresh.md
+
+🗑️ Cleaned up workspace:
+   - Archived: CONTEXT-SYSTEM-OVERVIEW.md → .tmp/archive/harvested/2026-01-06/
+   - Archived: SESSION-auth-work.md → .tmp/archive/harvested/2026-01-06/
+   - Deleted: .tmp/IMPLEMENTATION-NOTES.md (no valuable content)
+
+📊 Updated navigation maps:
+   - .plcode/context/core/navigation.md
+   - .plcode/context/development/navigation.md
+
+💾 Disk space freed: 6.8 KB
+```
+
+</workflow>
+
+---
+
+## Usage Examples
+
+### Scan entire workspace
+
+```bash
+/context harvest
+```
+
+### Scan specific directory
+
+```bash
+/context harvest .tmp/
+/context harvest docs/sessions/
+```
+
+### Harvest specific file
+
+```bash
+/context harvest OVERVIEW.md
+/context harvest SESSION-2026-01-06.md
+```
+
+---
+
+## Smart Content Detection
+
+### ✅ Extract (Valuable Knowledge)
+
+- Design decisions ("We chose X because...")
+- Patterns that worked ("This pattern solved...")
+- Errors encountered + solutions
+- API changes ("Updated from v1 to v2...")
+- Performance findings ("Optimization reduced...")
+- Core concepts explained
+
+### ❌ Skip (Temporary/Noise)
+
+- Planning discussion ("Should we...?", "Maybe try...")
+- Conversational notes ("I think...", "We talked about...")
+- Duplicate info (already in context)
+- TODO lists (move to task system instead)
+- Timestamps and session metadata
+
+---
+
+## Safety Features
+
+1. **Approval gate** - Never auto-delete without confirmation
+2. **Archive by default** - Move to .tmp/archive/, not permanent delete
+3. **Validation** - Check file sizes, structure before committing
+4. **Rollback** - Can restore from archive if needed
+5. **Dry run** - Show what would happen before doing it
+
+---
+
+## Success Criteria
+
+After harvest operation:
+
+- [ ] Valuable knowledge extracted to permanent context?
+- [ ] All extracted files <200 lines?
+- [ ] Files in correct function folders?
+- [ ] navigation.md navigation updated?
+- [ ] Summary files archived/deleted?
+- [ ] Workspace cleaner than before?
+- [ ] No knowledge lost?
+
+---
+
+## Related
+
+- compact.md - How to minimize extracted content
+- mvi-principle.md - What to extract
+- structure.md - Where files go
+- creation.md - File creation rules

package/.plcode/context/core/context-system/operations/organize.md

@@ -0,0 +1,245 @@
+# Organize Operation
+
+**Purpose**: Restructure flat context files into function-based folder structure
+
+**Last Updated**: 2026-01-06
+
+---
+
+## When to Use
+
+- Migrating from flat structure to function-based
+- Cleaning up disorganized context directories
+- Splitting ambiguous files into proper categories
+- Resolving duplicate/conflicting files
+
+---
+
+## 8-Stage Workflow
+
+### Stage 1: Scan
+
+**Action**: Scan category for all files and detect structure
+
+**Output**: List of files with current structure type (flat vs organized)
+
+---
+
+### Stage 2: Categorize
+
+**Action**: Categorize each file by function
+
+**Categorization Rules**:
+
+- Explains concept? → `concepts/`
+- Shows working code? → `examples/`
+- Step-by-step instructions? → `guides/`
+- Reference data (tables, commands)? → `lookup/`
+- Errors/issues? → `errors/`
+
+**Output**: Categorization plan with flagged ambiguous files
+
+---
+
+### Stage 3: Resolve Conflicts (APPROVAL REQUIRED)
+
+**Action**: Present categorization plan and handle conflicts
+
+**Format**:
+
+```
+Organizing {category}/ (23 files, flat structure)
+
+Clear categorization (18 files):
+  concepts/ (8):
+    ✓ authentication.md → concepts/authentication.md
+
+  examples/ (5):
+    ✓ jwt-example.md → examples/jwt-example.md
+
+Ambiguous files (5 - need your input):
+
+  [?] api-design.md (contains concepts AND steps)
+      → [A] Split: concepts/api-design.md + guides/api-design-guide.md
+      → [B] Keep as concepts/api-design.md
+      → [C] Keep as guides/api-design.md
+
+Conflicts (2):
+
+  [!] authentication.md → concepts/auth.md
+      Target already exists (120 lines)
+      → [J] Merge into existing
+      → [K] Rename to concepts/authentication-v2.md
+      → [L] Skip (keep flat)
+
+Select resolutions (A J or 'auto'):
+```
+
+**Validation**: MUST wait for user input
+
+---
+
+### Stage 4: Preview (APPROVAL REQUIRED)
+
+**Action**: Show preview of all changes
+
+**Format**:
+
+```
+Preview changes:
+
+CREATE directories:
+  {category}/concepts/
+  {category}/examples/
+  {category}/guides/
+  {category}/lookup/
+  {category}/errors/
+
+MOVE files (18):
+  authentication.md → concepts/authentication.md
+  ... (17 more)
+
+SPLIT files (3):
+  api-design.md → concepts/api-design.md + guides/api-design-guide.md
+
+MERGE files (2):
+  authentication.md → concepts/auth.md (merge content)
+
+UPDATE:
+  {category}/README.md
+  Fix 47 internal references
+
+Dry-run? (yes/no/show-diff):
+```
+
+**Dry-run**: Simulates changes without executing
+
+**Validation**: MUST get approval before proceeding
+
+---
+
+### Stage 5: Backup
+
+**Action**: Create backup before making changes
+
+**Location**: `.tmp/backup/organize-{category}-{timestamp}/`
+
+**Purpose**: Enable rollback if needed
+
+---
+
+### Stage 6: Execute
+
+**Action**: Perform the reorganization
+
+**Process**:
+
+1. Create function folders
+2. Move files to correct locations
+3. Split ambiguous files if requested
+4. Merge conflicts if requested
+
+---
+
+### Stage 7: Update
+
+**Action**: Update navigation and fix references
+
+**Process**:
+
+1. Update README.md with navigation tables
+2. Fix all internal references to moved files
+3. Validate all links work
+4. Update "Last Updated" dates
+
+---
+
+### Stage 8: Report
+
+**Action**: Show comprehensive results
+
+**Format**:
+
+```
+✅ Organized X files into function folders
+📁 Created Y new folders
+🔀 Split Z ambiguous files
+🔗 Fixed N references
+💾 Backup: .tmp/backup/organize-{category}-{timestamp}/
+
+Rollback available if needed.
+```
+
+---
+
+## Conflict Resolution
+
+### Ambiguous Files
+
+File fits multiple categories (e.g., has concepts AND steps)
+
+**Options**:
+
+- Split into multiple files (recommended)
+- Keep in primary category
+- User decides which is primary
+
+### Duplicate Targets
+
+Target file already exists
+
+**Options**:
+
+- Merge content into existing file
+- Rename to avoid conflict (e.g., -v2)
+- Skip (keep in flat structure)
+
+### Auto-Resolution
+
+Agent suggests best option based on:
+
+- File size
+- Content analysis
+- Existing structure
+
+---
+
+## Examples
+
+### Organize Flat Directory
+
+```bash
+/context organize development/
+```
+
+### Dry-Run First
+
+```bash
+/context organize development/ --dry-run
+```
+
+### Organize Multiple
+
+```bash
+/context organize development/
+/context organize core/
+```
+
+---
+
+## Success Criteria
+
+- [ ] All files in function folders (not flat)?
+- [ ] Ambiguous files resolved?
+- [ ] Conflicts handled?
+- [ ] README.md created/updated?
+- [ ] All references fixed?
+- [ ] Backup created?
+- [ ] User approved changes?
+
+---
+
+## Related
+
+- standards/structure.md - Folder organization rules
+- guides/workflows.md - Interactive examples