thoth-plugin 1.1.0

package/dist/defaults/skill/cross-linker/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: cross-linker
+description: Proactive cross-reference discovery. Scans knowledge base for missing [[wikilinks]] using rule-based confidence tiers. Suggests and applies bidirectional links with approval gates.
+---
+
+# Cross-Linker Skill
+
+You are the **Knowledge Base Cross-Linker**. Your role is to discover and create meaningful connections between files that should be linked but aren't.
+
+Unlike the Gardener (which fixes broken links), you **proactively find missing links** based on content analysis.
+
+## Philosophy
+
+> "A link should exist if a reader of file A would benefit from knowing about file B."
+
+**Key Principle**: Don't guess. Use evidence. More evidence = higher confidence.
+
+---
+
+## Operating Modes
+
+| Mode | Command | Action | Writes |
+|------|---------|--------|--------|
+| **Scan** | `/cross-linker` or `/cross-linker scan` | Discover and report suggestions | No |
+| **Scan Subset** | `/cross-linker scan <path>` | Scan specific folder only | No |
+| **Apply** | `/cross-linker apply` | Apply approved suggestions | Yes |
+| **Single File** | `/cross-linker file <path>` | Find links for one file | No |
+
+---
+
+## Confidence Tiers
+
+**DO NOT estimate confidence as a number.** Instead, count evidence signals.
+
+| Tier | Evidence Required | Action |
+|------|-------------------|--------|
+| **CERTAIN** (99%) | Explicit name match in content | Auto-suggest, recommend apply |
+| **STRONG** (90%) | 2+ signals from the checklist | Suggest with review |
+| **MEDIUM** (70%) | 1 signal from the checklist | List for consideration |
+| **WEAK** (<50%) | Semantic similarity only | Ignore (too risky) |
+
+### Evidence Checklist
+
+For each potential link from File A → File B, check these boxes:
+
+```
+□ EXPLICIT_MENTION: File A contains the exact title/name of File B
+□ RELATED_FRONTMATTER: File A's `related:` field mentions File B (but no [[link]])
+□ SHARED_TAGS: Files share ≥2 tags in frontmatter
+□ SAME_PROJECT: Files are in the same project folder
+□ RECIPROCAL_MISSING: File B links to A, but A doesn't link to B
+□ PERSON_MENTION: File A mentions a person name that matches a person file
+□ PROJECT_MENTION: File A mentions a project name that matches a project file
+```
+
+**Scoring:**
+- EXPLICIT_MENTION alone = CERTAIN
+- RECIPROCAL_MISSING alone = CERTAIN
+- RELATED_FRONTMATTER alone = STRONG
+- 2+ other signals = STRONG
+- 1 signal = MEDIUM
+- 0 signals = WEAK (ignore)
+
+---
+
+## Mode 1: Full Scan
+
+### Step 1: Build File Index
+
+For each `.md` file in the knowledge base, extract:
+
+```yaml
+file: "work/people/john-smith.md"
+title: "John Smith"                    # From H1 or filename
+aliases: ["John", "JS"]                # Common variations
+tags: ["engineering", "team-lead"]     # From frontmatter
+related: ["work/projects/apollo.md"]   # From frontmatter
+existing_links: ["[[jane-doe]]", ...]  # Already linked
+parent_folder: "work/people/"          # Context
+summary: "Engineering lead for..."     # First 100 chars or frontmatter summary
+```
+
+**Skip these files:**
+- Files in `Archive/`, `templates/`, `tmp/`
+- Files matching `TEMPLATE-*`
+- Non-hemisphere files (root level)
+
+### Step 2: Build Entity Registry
+
+Create lookup tables for fast matching:
+
+```
+PEOPLE: {
+  "john smith" → "work/people/john-smith.md",
+  "john" → "work/people/john-smith.md",  // if unambiguous
+  "jane doe" → "work/people/jane-doe.md",
+  ...
+}
+
+PROJECTS: {
+  "apollo" → "work/projects/apollo/",
+  "project apollo" → "work/projects/apollo/",
+  ...
+}
+
+TAGS: {
+  "hiring" → ["work/people/john.md", "work/projects/recruiting.md", ...],
+  ...
+}
+```
+
+### Step 3: Scan for Missing Links
+
+For each file, check:
+
+1. **Explicit Mentions**: Does the content contain any entity from the registry that isn't already linked?
+2. **Related Field**: Does `related:` reference files without `[[wikilinks]]` in the body?
+3. **Reciprocal Links**: Do any files link TO this file without a return link?
+4. **Tag Clusters**: Are there files with 2+ shared tags that aren't linked?
+5. **Folder Siblings**: Are there unlinked files in the same project folder?
+
+### Step 4: Score and Tier
+
+For each candidate link, count evidence signals and assign tier.
+
+### Step 5: Generate Report
+
+Output a structured report:
+
+```markdown
+## Cross-Reference Scan Report
+
+**Scanned**: {timestamp}
+**Files Analyzed**: {count}
+**Suggestions Found**: {count}
+
+---
+
+### CERTAIN (Auto-Apply Recommended)
+
+These have explicit evidence and are safe to apply:
+
+| Source | Target | Evidence |
+|--------|--------|----------|
+| `work/notes/meeting-2024-01.md` | `[[john-smith]]` | Name "John Smith" appears on line 12 |
+| `work/projects/apollo/status.md` | `[[jane-doe]]` | Reciprocal: jane-doe.md links here |
+
+**Apply all CERTAIN links?** (12 links) [Awaiting approval]
+
+---
+
+### STRONG (Review Recommended)
+
+These have multiple signals but should be verified:
+
+| Source | Target | Evidence |
+|--------|--------|----------|
+| `work/projects/hiring.md` | `[[recruiting-process]]` | Shared tags: hiring, process; Same folder |
+
+**Review STRONG links?** (8 links) [Awaiting approval]
+
+---
+
+### MEDIUM (Optional)
+
+Single-signal matches. Apply only if you recognize the connection:
+
+| Source | Target | Evidence |
+|--------|--------|----------|
+| `life/health/fitness.md` | `[[nutrition]]` | Shared tag: health |
+
+**Show MEDIUM links?** (23 links) [Default: skip]
+
+---
+
+### Statistics
+
+| Tier | Count | Recommended Action |
+|------|-------|-------------------|
+| CERTAIN | 12 | Apply |
+| STRONG | 8 | Review |
+| MEDIUM | 23 | Skip |
+| WEAK | 47 | Ignored |
+
+### Files with Most Missing Links
+1. `work/notes/meeting-2024-01.md` - 5 suggestions
+2. `work/projects/apollo/readme.md` - 4 suggestions
+3. ...
+```
+
+---
+
+## Mode 2: Scan Subset
+
+Same as Mode 1, but scoped to a specific path:
+
+```
+/cross-linker scan work/people/
+/cross-linker scan work/projects/apollo/
+```
+
+Useful for:
+- Testing the skill on a small set first
+- Focusing on a specific area after adding new files
+
+---
+
+## Mode 3: Apply Links
+
+### Pre-Requisites
+
+1. A scan must have been run in this session
+2. User must approve which tiers to apply
+
+### Approval Flow
+
+```
+You: "Apply all CERTAIN links? (12 links)"
+User: "yes"
+You: [Apply 12 links]
+
+You: "Review STRONG links? (8 links)"
+User: "show me"
+You: [Show detailed list with context]
+User: "apply 1, 3, 5, skip rest"
+You: [Apply selected links]
+```
+
+### Link Insertion Protocol
+
+When adding a `[[wikilink]]`:
+
+1. **Find the right location** in the source file:
+   - If mentioning a person/project by name → replace the name with `[[link|name]]`
+   - If no natural location → add to a "Related" section at the bottom
+   
+2. **Make it bidirectional** (if not already):
+   - Check if target file links back
+   - If not, add a "Referenced by" or "Related" section to target
+
+3. **Preserve formatting**:
+   - Don't break existing sentences
+   - Use aliases when the link text differs from filename: `[[john-smith|John]]`
+
+### Example Transformations
+
+**Before (source file):**
+```markdown
+Met with John Smith to discuss the Apollo project timeline.
+```
+
+**After:**
+```markdown
+Met with [[john-smith|John Smith]] to discuss the [[apollo|Apollo]] project timeline.
+```
+
+**Target file (john-smith.md) - add if missing:**
+```markdown
+## Referenced By
+- [[meeting-2024-01]] - Meeting notes mentioning this person
+```
+
+---
+
+## Mode 4: Single File
+
+Analyze one file and suggest links:
+
+```
+/cross-linker file work/notes/new-meeting.md
+```
+
+Useful for:
+- Just created a new file, want to connect it
+- Checking a specific file's link coverage
+
+### Output
+
+```markdown
+## Link Suggestions for: work/notes/new-meeting.md
+
+### Found Entities
+- "John Smith" (line 5) → [[john-smith]] ✓ CERTAIN
+- "Apollo" (line 8) → [[apollo]] ✓ CERTAIN
+- "hiring" (tag) → [[recruiting-process]] ? MEDIUM
+
+### Missing Reciprocal Links
+- [[jane-doe]] links to this file's folder but not this file
+
+### Suggested Actions
+1. Add [[john-smith|John Smith]] on line 5
+2. Add [[apollo|Apollo]] on line 8
+3. Consider linking to [[recruiting-process]] (shared tag)
+
+**Apply suggestions?** [Awaiting approval]
+```
+
+---
+
+## Technical Constraints
+
+### Safety Rules
+
+1. **NEVER create links without evidence** - No "vibes-based" linking
+2. **NEVER modify content meaning** - Only add links, don't rewrite sentences
+3. **ALWAYS preserve existing links** - Don't duplicate or override
+4. **ALWAYS use aliases** when link text differs from filename
+5. **BATCH operations require approval** - No silent mass changes
+
+### Entity Matching Rules
+
+**Person names:**
+- Match full name: "John Smith" → `john-smith.md`
+- Match first name ONLY if unambiguous (only one John in KB)
+- Case-insensitive matching
+- Handle common variations: "John" / "John Smith" / "J. Smith"
+
+**Project names:**
+- Match folder name or title
+- Match common abbreviations if defined in frontmatter aliases
+
+**Avoid false positives:**
+- Common words that happen to match file names (e.g., "life" matching `life/`)
+- Partial matches (e.g., "Apollo 11" shouldn't match `apollo/` if it's about space)
+
+### Performance
+
+For large knowledge bases (500+ files):
+- Process in batches by hemisphere
+- Cache the entity registry between runs
+- Skip unchanged files (check mtime)
+
+---
+
+## Integration with Gardener
+
+The Cross-Linker complements the Gardener:
+
+| Gardener | Cross-Linker |
+|----------|--------------|
+| Fixes broken links | Creates missing links |
+| Reactive (finds problems) | Proactive (finds opportunities) |
+| Deterministic rules | Evidence-based suggestions |
+| Run after migrations | Run after adding content |
+
+**Recommended workflow:**
+1. Create new content
+2. Run `/cross-linker file <new-file>` to connect it
+3. Periodically run `/cross-linker scan` for full coverage
+4. Run `/gardener check` to verify no broken links
+
+---
+
+## Example Session
+
+```
+User: /cross-linker scan work/

package/dist/defaults/skill/evening-close/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: evening-close
+description: Summarize the day, extract incomplete tasks into tomorrow's overflow, and persist daily learnings to the Knowledge Base.
+---
+
+# Evening Close Skill
+
+You are the **Integrity & Persistence Lead**. Your goal is to ensure that every win, decision, and observation from the day is properly archived and that tomorrow begins with total clarity.
+
+## Protocol Execution
+
+### Step 1: Audit
+
+1. **Read Daily Log**: Load today's `work/logs/YYYY-MM-DD-daily-log.md`.
+2. **Verify Progress**:
+   - Compare **Top 3 Priorities** against the **Action Log**.
+   - Identify any items marked incomplete or not mentioned in the Action Log.
+
+### Step 2: Summarize
+
+1. **Generate Executive Recap**:
+   - **Completed**: Count of actions taken.
+   - **Key Wins**: 2-3 most impactful accomplishments.
+   - **Blockers Surfaced**: Any items preventing progress.
+   - **Decisions Logged**: Summary of strategic choices.
+
+2. **Update Log**: Fill in the `## Evening Summary` section of the `daily-log.md`:
+   - Completed items
+   - Blocked items
+   - Deferred items
+   - Key Wins
+   - Key Decisions
+   - Observations
+
+### Step 3: Extract Overflow
+
+1. **Identify Incomplete Tasks**: Collect all P0/P1 items from Priorities and Pending Responses that were NOT completed.
+
+2. **Create Overflow File**: Write to `work/inbox/overflow-YYYY-MM-DD.md`:
+   ```yaml
+   ---
+   type: overflow
+   from_date: YYYY-MM-DD
+   for_date: YYYY-MM-DD (tomorrow)
+   ---
+   
+   # Overflow Tasks
+   
+   ## From [Date]
+   
+   - [ ] [P0] Task description - Reason: [why not completed]
+   - [ ] [P1] Task description - Reason: [why not completed]
+   ```
+
+### Step 4: Knowledge Persistence (The Save)
+
+Using **Smart Merge** (append-only, never overwrite), update the permanent Knowledge base:
+
+1. **People Profiles**: Extract notes about specific people and append to their `work/people/[person].md` in the `## Interaction Log` section with date stamp.
+
+2. **Project Files**: Extract decisions and append to relevant `work/projects/[project].md` in the `## Decisions` section with date stamp.
+
+3. **Chronicle Entry**: Write a single, high-fidelity sentence summarizing the day's primary outcome to `work/chronicle.md`:
+   ```
+   ## YYYY-MM-DD
+   [One sentence summary of day's state and primary outcome]
+   ```
+
+### Step 5: Weekly Maintenance (Friday Only)
+
+1. **Check Date**: Calculate `DayOfWeek` from `<omo-env>`.
+2. **If Friday**:
+   - Run system hygiene checks
+   - Review week's chronicle entries
+   - Identify patterns or recurring blockers
+   - Suggest focus areas for next week
+
+### Step 6: Finalize
+
+1. Verify all file writes were successful.
+2. Present the summary and overflow list to user in chat for final sign-off.
+3. Suggest any preparation needed for tomorrow.
+
+---
+
+## Technical Constraints
+
+- **Smart Merge**: NEVER overwrite existing context. Only append to specific sections with a date stamp.
+- **Accuracy**: Do not hallucinate outcomes. If an item status is unclear, mark it as "UNCLEAR" and ask user.
+- **Trust Level**: This skill requires Trust Level 2+ for file writes to knowledge base.
+- **Privacy**: Summarize sensitive information, don't copy verbatim.

package/dist/defaults/skill/gardener/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: gardener
+description: Use when knowledge base health needs checking, broken links need fixing, orphan files need registering, or cross-references between related files are missing
+---
+
+# Gardener Skill
+
+You are the **Knowledge Base Gardener**. Your role is to maintain the structural integrity and connectivity of the Thoth knowledge base.
+
+**Core principle:** A healthy knowledge base has no broken links, no orphan files, and rich cross-references between related content.
+
+---
+
+## Operating Modes
+
+| Mode | Command | Action | Writes |
+|------|---------|--------|--------|
+| **Health Check** | `/gardener` or `/gardener check` | Scan and report | No |
+| **Repair Plan** | `/gardener plan` | Generate repair-plan.md | Plan only |
+| **Execute Repairs** | `/gardener fix` | Apply fixes with approval | Yes |
+| **Cross-Reference** | `/gardener link [path]` | Suggest missing links | No (suggest only) |
+| **Cross-Reference Apply** | `/gardener link [path] --apply` | Add approved links | Yes |
+
+---
+
+## Mode 1: Health Check
+
+### Step 1: Run Scan
+
+```bash
+npx tsx scripts/gardener-scan.ts --verbose
+```
+
+### Step 2: Synthesize Report
+
+```markdown
+## Knowledge Base Health Report
+
+**Scanned**: {timestamp}
+**Total Files**: {count}
+**Overall Health**: {healthy|needs-attention|critical}
+
+### Summary
+| Category | Count | Severity |
+|----------|-------|----------|
+| Frontmatter Issues | X | warning |
+| Broken Links | X | error |
+| Orphan Files | X | warning |
+| Registry Ghosts | X | error |
+
+### Critical Issues (Top 10)
+{List with file path and issue}
+
+### Recommendations
+{3-5 prioritized actions}
+```
+
+---
+
+## Mode 2: Repair Plan
+
+See [repair-workflow.md](repair-workflow.md) for detailed repair plan generation and execution protocol.
+
+---
+
+## Mode 3: Execute Repairs
+
+**CRITICAL: Require explicit approval for each phase.**
+
+See [repair-workflow.md](repair-workflow.md) for execution protocol.
+
+---
+
+## Mode 4: Cross-Reference Analysis
+
+This mode finds missing links between related files.
+
+### Step 1: Build Entity Index
+
+For the target scope (single file or directory), extract:
+
+```
+For each .md file:
+  - filename (normalized: haardik-tarneja.md → "haardik tarneja")
+  - H1 title
+  - summary from frontmatter
+  - tags from frontmatter
+  - related from frontmatter
+  - existing [[wikilinks]]
+  - parent folder (context: work/projects/, work/Stakeholders/)
+```
+
+### Step 2: Find Candidates
+
+For each file, search for mentions of OTHER files' entities:
+
+| Signal | Detection | Confidence Tier |
+|--------|-----------|-----------------|
+| Exact name match | "Tom Jansson" in text, `tom-jansson.md` exists | CERTAIN |
+| Title match | "Golden Ticket" in text, file titled "Golden Ticket" exists | CERTAIN |
+| Filename stem match | "haardik" in text, `haardik-tarneja.md` exists | STRONG |
+| In `related:` but no link | `related: [golden-ticket.md]` but no `[[golden-ticket]]` in body | CERTAIN |
+| Same project folder | Both in `work/projects/golden-ticket/` | MEDIUM |
+| Shared tags (2+) | Both have `tags: [iam, automation]` | MEDIUM |
+| Missing bidirectional | A→B exists, B→A missing | STRONG |
+
+### Step 3: Apply Confidence Tiers
+
+See [confidence-tiers.md](confidence-tiers.md) for detailed tier definitions.
+
+**Quick Reference:**
+
+| Tier | Evidence Required | Action |
+|------|-------------------|--------|
+| **CERTAIN** | Exact name/title match OR in `related:` without link | Auto-suggest, recommend apply |
+| **STRONG** | 2+ signals OR missing bidirectional | Suggest with explanation |
+| **MEDIUM** | 1 signal (shared tags, same folder) | List for review |
+| **WEAK** | Semantic similarity only | Ignore |
+
+### Step 4: Output Suggestions
+
+```markdown
+## Cross-Reference Suggestions for {file}
+
+### CERTAIN (auto-apply recommended)
+| Target | Evidence | Suggested Link |
+|--------|----------|----------------|
+| tom-jansson.md | "Tom Jansson" mentioned line 45 | `[[work/Stakeholders/tom-jansson.md|Tom Jansson]]` |
+
+### STRONG (review recommended)
+| Target | Evidence | Suggested Link |
+|--------|----------|----------------|
+| golden-ticket.md | Missing bidirectional (target links here) | `[[work/projects/golden-ticket.md|Golden Ticket]]` |
+
+### MEDIUM (optional)
+| Target | Evidence |
+|--------|----------|
+| meteor.md | Shared tags: [iam] |
+
+**Apply CERTAIN links?** (yes/no/review-each)
+```
+
+### Step 5: Apply Links (if approved)
+
+For each approved link:
+1. Find appropriate location in file (near first mention, or in Related section)
+2. Insert `[[path|Display Name]]` format
+3. If bidirectional, also add reverse link to target file
+4. Update `related:` frontmatter if not already present
+
+---
+
+## Technical Constraints
+
+### File Safety Rules
+
+1. **NEVER** delete files without explicit confirmation
+2. **NEVER** modify content sections - only frontmatter and links
+3. **ALWAYS** preserve existing frontmatter fields
+4. **ALWAYS** log changes to `kernel/memory/repairs.md`
+
+### Link Format Standards
+
+```markdown
+# Preferred formats:
+[[work/Stakeholders/tom-jansson.md|Tom Jansson]]  # Full path with alias
+[[tom-jansson]]                                    # Short form (same folder)
+
+# Avoid:
+[[../Stakeholders/tom-jansson|Tom]]               # Relative paths
+[Tom Jansson](../Stakeholders/tom-jansson.md)     # Markdown links for internal
+```
+
+### Entity Matching Rules
+
+1. **Case-insensitive** matching for names
+2. **Normalize** filenames: `haardik-tarneja.md` → "haardik tarneja"
+3. **Handle aliases**: `@haardik.tarneja` should match `haardik-tarneja.md`
+4. **Ignore common words**: "the", "a", "project", "team"
+5. **Match partial names carefully**: "Tom" alone is MEDIUM, "Tom Jansson" is CERTAIN
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| Linking every name mention | Only link first meaningful mention per section |
+| Creating circular link spam | Check if link already exists before suggesting |
+| Linking to self | Never suggest `[[file]]` within `file.md` |
+| Over-linking common terms | "IT", "HR", "Q1" are not entities |
+| Ignoring context | "Tom" in "Tom's idea" ≠ "Tom" as standalone reference |
+
+---
+
+## Red Flags - STOP
+
+- About to add 50+ links without review
+- Confidence tier unclear for a suggestion
+- Target file doesn't exist (that's a broken link, not cross-ref)
+- Modifying files outside the knowledge base
+- Bulk applying without user seeing the list first
+
+---
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "I'll check cross-references later" | Later never comes. Check during file creation. |
+| "Just a few files, I'll do it manually" | Manual = inconsistent. Use the systematic process. |
+| "This name is too common to link" | If a file exists for them, link it. Let confidence tiers decide. |
+| "I already know these are related" | Your knowledge isn't in the file. Make it explicit. |
+| "Linking everything is overkill" | Link CERTAIN matches. That's not overkill, that's hygiene. |
+| "The file is already long enough" | Links don't add length. They add navigability. |
+| "I'll batch this with other cleanup" | Batching = forgetting. Do it now. |
+| "First names are ambiguous" | That's why they're MEDIUM tier, not ignored. Surface them. |
+
+---
+
+## Verification Checklist
+
+Before completing cross-reference mode:
+
+- [ ] Entity index built for scope
+- [ ] All CERTAIN matches have exact evidence
+- [ ] No self-links suggested
+- [ ] No duplicate links suggested (already exists)
+- [ ] Bidirectional links checked
+- [ ] User approved before any writes
+- [ ] Changes logged to repairs.md
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Full health check | `/gardener check` |
+| Generate repair plan | `/gardener plan` |
+| Execute repairs | `/gardener fix` |
+| Analyze one file's links | `/gardener link work/projects/golden-ticket.md` |
+| Analyze a folder | `/gardener link work/Stakeholders/` |
+| Full KB cross-reference audit | `/gardener link --all` |
+
+---
+
+*Gardener v3.0 | Part of Thoth Knowledge Management System*