xtrm-tools 0.7.2 → 0.7.4

package/.xtrm/skills/default/specialists-creator/scripts/validate-specialist.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { parseSpecialist } from "../../../src/specialist/schema.ts";
+
+function printUsage(): void {
+  console.error("Usage: bun skills/specialist-author/scripts/validate-specialist.ts <path-to.specialist.yaml>");
+}
+
+const file = process.argv[2];
+
+if (!file) {
+  printUsage();
+  process.exit(64);
+}
+
+let yaml: string;
+try {
+  yaml = readFileSync(file, "utf8");
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`File not found or unreadable: ${file}`);
+  console.error(message);
+  process.exit(66);
+}
+
+try {
+  await parseSpecialist(yaml);
+  console.log(`OK ${file}`);
+} catch (error) {
+  console.error(`Invalid ${file}`);
+  if (error && typeof error === "object" && "issues" in error && Array.isArray(error.issues)) {
+    for (const issue of error.issues) {
+      const path = Array.isArray(issue.path) && issue.path.length > 0 ? issue.path.join(".") : "<root>";
+      console.error(`- ${path}: ${issue.message}`);
+    }
+  } else if (error instanceof Error) {
+    console.error(error.message);
+  } else {
+    console.error(String(error));
+  }
+  process.exit(1);
+}

package/.xtrm/skills/default/sync-docs/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: sync-docs
+description: >-
+  Mode-routed documentation sync for xtrm projects. Three modes: targeted
+  (named docs only), area (time-windowed + source scope), full audit.
+  Commit-based context gathering, not PR-based. Use whenever docs need
+  syncing after code changes, the user asks to "sync docs", "update docs",
+  "doc audit", "check docs health", or "detect drift".
+gemini-command: sync-docs
+version: 2.0.0
+---
+
+# sync-docs
+
+Keeps project documentation in sync with code reality.
+
+## Overview
+
+```
+Phase 0: Route mode/scope   — targeted, area, or full audit?
+Phase 1: Gather context      — commits, issues, changed files in window
+Phase 2: Inspect with xtrm   — what does the docs suite report?
+Phase 3: Detect drift         — which docs are stale?
+Phase 4: Plan delta           — what to edit vs report
+Phase 5: Execute fixes        — update docs within scope
+Phase 6: Validate             — confirm no remaining drift
+```
+
+**Audit vs Execute:** Bead-linked runs execute all phases. Non-bead runs with
+"audit/check/report" stop after Phase 4. Non-bead runs with "update/fix/sync"
+execute.
+
+---
+
+## Phase 0: Route Mode and Scope
+
+Determine your mode BEFORE gathering context. This controls everything downstream.
+
+### Mode precedence
+
+| Priority | Condition | Mode |
+|----------|-----------|------|
+| 1 | Prompt contains explicit doc file paths | **Targeted** |
+| 2 | Prompt contains time window + directory/source scope | **Area** |
+| 3 | Everything else | **Full audit** |
+
+### Mode behaviors
+
+**Targeted** — edit ONLY the named docs. Gather recent context for understanding.
+Report collateral docs that likely also need updates but do NOT edit them.
+
+**Area** — derive candidate docs from changed source paths within the time window.
+Use drift detector to confirm staleness. Edit candidate docs within derived scope.
+
+**Full audit** — run complete docs audit. Contextualize with recent commits/issues.
+Use drift detector + structure analyzer for comprehensive coverage.
+
+### Execution policy
+
+| Condition | Action |
+|-----------|--------|
+| `$bead_id` present | Execute (all phases) |
+| No bead + "audit"/"check"/"report"/"what's stale" | Report only (stop Phase 4) |
+| No bead + "update"/"fix"/"sync" | Execute |
+
+---
+
+## Phase 1: Gather Scoped Context
+
+### Context gatherer
+
+The context gatherer supports time-window and scope-aware gathering:
+
+```bash
+# Targeted: specific docs + time window
+python3 .xtrm/skills/default/sync-docs/scripts/context_gatherer.py \
+  --doc docs/features.md --doc docs/cli-reference.md --since-hours 24
+
+# Area: source scope + time window
+python3 .xtrm/skills/default/sync-docs/scripts/context_gatherer.py \
+  --scope-path src/specialist/ --since-hours 24
+
+# Area: broader window
+python3 .xtrm/skills/default/sync-docs/scripts/context_gatherer.py \
+  --scope-path src/cli/ --since-days 7
+
+# Full audit: broad window
+python3 .xtrm/skills/default/sync-docs/scripts/context_gatherer.py \
+  --since-days 7
+
+# Legacy compat (commit count)
+python3 .xtrm/skills/default/sync-docs/scripts/context_gatherer.py \
+  --since-commits 30
+```
+
+**Default:** `--since-hours 24` when no window specified.
+
+Outputs JSON with:
+- `mode_hint`: targeted / area / full
+- `window`: type + value + git_since
+- `scope`: doc targets + source paths
+- `git.recent_commits`: commits with changed files
+- `git.changed_files`: unique files ranked by change frequency
+- `git.changed_dirs`: directory-level summary
+- `bd.closed_issues`: recently closed issues
+- `docs`: drift detector results
+
+### xtrm docs suite
+
+Use for operator-facing inspection:
+
+```bash
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
+```
+
+---
+
+## Phase 2: Inspect Docs State
+
+Use `xtrm docs` to answer:
+- What docs exist and their metadata?
+- Which have missing or outdated frontmatter?
+- Coverage gaps between recent work and docs?
+
+If the CLI already isolates the problem clearly, skip to Phase 4.
+
+---
+
+## Phase 3: Detect Drift
+
+Use the drift detector filtered to your scope:
+
+```bash
+# All docs
+python3 .xtrm/skills/default/sync-docs/scripts/drift_detector.py scan --json
+
+# With commit window
+python3 .xtrm/skills/default/sync-docs/scripts/drift_detector.py scan --since 30 --json
+```
+
+A doc is stale when:
+1. It declares `source_of_truth_for` globs in frontmatter
+2. AND commits affecting matching files exist AFTER the `synced_at` hash
+
+### Staleness model
+
+- **Time windows** decide what recent work to consider now (relevance)
+- **`synced_at` / hash-based drift** decides whether a doc is actually stale (truth)
+- **Fallback**: when metadata is missing, time-window heuristics prioritize review
+
+---
+
+## Phase 4: Plan Delta
+
+Before editing, identify:
+- Docs to update (within scope)
+- Docs to leave untouched
+- Collateral docs to report only (targeted mode)
+
+**If audit-only, stop here and output the report.**
+
+Include both:
+- `xtrm docs` findings (operator-facing)
+- Python analyzer findings (drift/structure enforcement)
+
+---
+
+## Phase 5: Execute Fixes
+
+| Situation | Action |
+|-----------|--------|
+| Stale docs file | Update content + bump `version` + `updated` |
+| README bloated | Extract large sections to focused docs files |
+| Missing docs file | Generate scaffold via `validate_doc.py --generate` |
+| Stale CHANGELOG | Add entry with changelog script |
+| Invalid schema | Fix frontmatter |
+
+### After each doc update
+
+Stamp the sync checkpoint:
+```bash
+python3 .xtrm/skills/default/sync-docs/scripts/drift_detector.py update-sync <doc-path>
+```
+
+### Targeted mode boundary
+
+In targeted mode, ONLY edit the named docs. If you discover other docs need
+updating, list them in your output as "Suggested follow-ups" — do not edit them.
+
+### Structure analysis (full audit only)
+
+```bash
+python3 .xtrm/skills/default/sync-docs/scripts/doc_structure_analyzer.py
+python3 .xtrm/skills/default/sync-docs/scripts/doc_structure_analyzer.py --fix
+```
+
+### Add changelog entry
+
+```bash
+python3 .xtrm/skills/default/sync-docs/scripts/changelog/add_entry.py \
+  CHANGELOG.md Added "Describe the documentation update"
+```
+
+---
+
+## Phase 6: Validate
+
+Re-run both layers:
+
+```bash
+xtrm docs list --json
+xtrm docs cross-check --json --days 30
+python3 .xtrm/skills/default/sync-docs/scripts/drift_detector.py scan --json
+```
+
+Confirm updated docs no longer show as stale.
+
+---
+
+## Frontmatter Schema
+
+All `docs/*.md` files require valid YAML frontmatter.
+
+### Required Fields
+
+| Field | Format | Example |
+|-------|--------|---------|
+| `title` | string | `"Hooks Reference"` |
+| `scope` | string | `hooks` |
+| `category` | enum | `reference` |
+| `version` | semver | `1.0.0` |
+| `updated` | date | `2026-03-22` |
+
+### Valid Categories
+
+`api` | `architecture` | `guide` | `overview` | `plan` | `reference`
+
+### Optional Fields
+
+| Field | Format | Use |
+|-------|--------|-----|
+| `description` | string | Brief summary |
+| `source_of_truth_for` | list of globs | Link to code areas |
+| `synced_at` | git hash | Drift checkpoint |
+| `domain` | list of tags | Categorization |
+
+---
+
+## Command Selection Rules
+
+**`xtrm docs` first** for understanding current docs state:
+- `xtrm docs list --json` — inventory
+- `xtrm docs show --json` — frontmatter inspection
+- `xtrm docs cross-check --json` — drift, coverage gaps
+
+**Python scripts** for enforcement and sync internals:
+- `drift_detector.py` — `synced_at` / `source_of_truth_for` checks
+- `doc_structure_analyzer.py` — README bloat, missing docs, changelog gaps
+- `validate_metadata.py` / `validate_doc.py` — schema/index validation
+- `context_gatherer.py` — scoped commit/issue context for sync decisions

package/.xtrm/skills/default/sync-docs/evals/evals.json

@@ -0,0 +1,89 @@
+{
+  "skill_name": "sync-docs",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just closed a bunch of bd issues this sprint and merged 3 PRs. The README.md is getting long — can you sync the docs and make sure everything's in order? Use sync-docs.",
+      "expected_output": "Runs context_gatherer.py and doc_structure_analyzer.py, reports what was found (closed issues, PRs, any drift), identifies README extraction candidates or MISSING docs/ files, and either fixes them or gives a clear plan with next steps.",
+      "files": [],
+      "assertions": [
+        {
+          "id": "ran-context-gatherer",
+          "description": "Ran context_gatherer.py and reported bd closed issues or merged PRs from the output",
+          "check": "result.md mentions context_gatherer or bd closed issues or merged PRs with specific data"
+        },
+        {
+          "id": "ran-structure-analyzer",
+          "description": "Ran doc_structure_analyzer.py and used its output to identify doc issues",
+          "check": "result.md references MISSING, STALE, EXTRACTABLE, or BLOATED status from the analyzer"
+        },
+        {
+          "id": "concrete-action",
+          "description": "Produced at least one concrete recommendation or action (not just a vague summary)",
+          "check": "result.md names a specific file (e.g. docs/hooks.md) or section with a specific next step"
+        },
+        {
+          "id": "used-skill-scripts",
+          "description": "Used the skill scripts rather than just reading files manually",
+          "check": "result.md shows script execution output, not just manual file reading"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Run sync-docs --fix on this project and remember what you did with bd.",
+      "expected_output": "Runs doc_structure_analyzer.py --fix --bd-remember, creates scaffold files for any missing docs/ subsystems, persists a bd memory with the summary, then validates the created files with validate_doc.py.",
+      "files": [],
+      "assertions": [
+        {
+          "id": "ran-fix-flag",
+          "description": "Ran doc_structure_analyzer.py with --fix flag",
+          "check": "result.md shows the --fix command was executed"
+        },
+        {
+          "id": "ran-bd-remember",
+          "description": "Ran with --bd-remember or manually ran bd remember with a summary",
+          "check": "result.md shows bd remember was called and reports the memory key"
+        },
+        {
+          "id": "scaffold-created",
+          "description": "At least one scaffold file was created in docs/",
+          "check": "result.md lists a docs/*.md file created, OR reports no gaps found (valid outcome)"
+        },
+        {
+          "id": "validated-schema",
+          "description": "Ran validate_doc.py on created files to confirm schema",
+          "check": "result.md shows validate_doc.py was run and reports pass/fail for created files"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Do a doc audit. I think the README has sections that should be in docs/ but I'm not sure which ones.",
+      "expected_output": "Runs the full 5-phase sync-docs workflow: gathers context, runs drift detection, runs doc_structure_analyzer.py, and identifies EXTRACTABLE/BLOATED sections with specific suggestions for what goes in which docs/ file before recommending or making changes.",
+      "files": [],
+      "assertions": [
+        {
+          "id": "ran-analyzer",
+          "description": "Ran doc_structure_analyzer.py and referenced its structured output",
+          "check": "result.md cites the analyzer output (EXTRACTABLE, BLOATED, line count, or specific section names from the report)"
+        },
+        {
+          "id": "named-specific-sections",
+          "description": "Named specific README sections with their suggested docs/ destination",
+          "check": "result.md lists at least 2 specific sections (e.g. '## Policy System → docs/policies.md') not just generic advice"
+        },
+        {
+          "id": "actionable-report",
+          "description": "Report is actionable — tells user exactly what to do next, not just observations",
+          "check": "result.md includes a prioritized list or clear next steps, not just 'the README could be shorter'"
+        },
+        {
+          "id": "no-edits-made",
+          "description": "Did not edit or create any files (audit only)",
+          "check": "result.md does not claim to have modified README.md or created docs/ files"
+        }
+      ]
+    }
+  ]
+}

package/.xtrm/skills/default/sync-docs/references/doc-structure.md

@@ -0,0 +1,99 @@
+# docs/ Structure Guide
+
+This reference defines what belongs in each focused docs/ file vs README.md.
+
+## The Rule
+
+**README.md** is an entry point — a quick-start and orientation map. It should be < 200 lines. Anything that requires more than a few bullet points belongs in a focused docs/ file.
+
+**docs/** holds focused, public-facing SSOT files for each subsystem. Each file:
+- Has YAML frontmatter (see `schema.md`)
+- Covers exactly one subsystem or concern
+- Is linked from README.md with a single line
+
+---
+
+## What Goes Where
+
+| Content Type | Location | When to Create |
+|---|---|---|
+| Quick start, one-liner install | `README.md` | Always |
+| Feature overview table | `README.md` | Always, < 20 lines |
+| Hook events, scripts, behavior | `docs/hooks.md` | When hooks/ dir exists |
+| Pi/Copilot extension catalog | `docs/pi-extensions.md` | When config/pi/extensions/ exists |
+| System architecture, components | `docs/architecture.md` | When > 2 major subsystems |
+| Policy rules and enforcement | `docs/policies.md` | When policies/ dir exists |
+| MCP server config and usage | `docs/mcp-servers.md` | When .mcp.json or mcp servers exist |
+| Skills catalog | `docs/skills.md` | When skills/ dir has > 5 skills |
+| CLI commands reference | `docs/cli-reference.md` | When CLI has > 10 commands |
+| Troubleshooting and FAQs | `docs/troubleshooting.md` | When recurring issues exist |
+| In-progress work plans | `docs/plans/` | Always for planning docs |
+
+---
+
+## Standard File Shapes
+
+### docs/hooks.md
+Covers: hook events, what triggers each hook, which scripts run, output format.
+Section outline:
+```
+## Overview
+## Hook Events
+## Scripts Reference
+## Adding a New Hook
+```
+
+### docs/pi-extensions.md
+Covers: what Pi extensions are installed, their events, behavior, and configuration.
+Section outline:
+```
+## Overview
+## Installed Extensions
+## Extension Events
+## Configuration
+```
+
+### docs/architecture.md
+Covers: system overview, key components, data flow, dependency diagram.
+Section outline:
+```
+## System Overview
+## Key Components
+## Data Flow
+## Directory Structure
+```
+
+### docs/policies.md
+Covers: what policies exist, what each enforces, runtime targets.
+Section outline:
+```
+## Overview
+## Policy Files
+## Policy Compiler
+## Adding a Policy
+```
+
+---
+
+## Detecting When README is Too Big
+
+The `doc_structure_analyzer.py` script flags README as `BLOATED` when:
+1. Line count > 200, AND
+2. At least one section has a matching `docs/` file that doesn't exist yet
+
+The `EXTRACTABLE` status means sections are present but README isn't over threshold yet — worth noting but not urgent.
+
+---
+
+## Extraction Process
+
+When extracting a section from README to docs/:
+
+1. Identify the target section heading and its body in `README.md`
+2. Create `docs/X.md` with `validate_doc.py --generate`
+3. Move the section content into the new file
+4. Replace the original README section with:
+   ```markdown
+   See [docs/X.md](docs/X.md) for the full reference.
+   ```
+5. Run `validate_doc.py docs/X.md` to confirm schema

package/.xtrm/skills/default/sync-docs/references/schema.md

@@ -0,0 +1,103 @@
+# docs/ File Schema
+
+Every file in `docs/` must have YAML frontmatter. This is enforced by `validate_doc.py`.
+
+## Frontmatter Fields
+
+```yaml
+---
+title: Human Readable Title          # required — clear, descriptive
+scope: kebab-case-identifier         # required — unique slug for this doc
+category: reference                  # required — see valid values below
+version: 1.0.0                       # required — semver (x.y.z)
+updated: 2026-03-18                  # required — ISO date of last update
+description: "One-line summary"      # optional
+source_of_truth_for:                 # optional — glob patterns this doc describes
+  - "hooks/**/*.mjs"
+  - "policies/*.json"
+domain: [hooks, claude, policy]      # optional — cross-cutting tags
+---
+```
+
+## Required Fields
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `title` | string | Clear, descriptive title | "Hooks Reference" |
+| `scope` | string | Unique kebab-case slug | "hooks" |
+| `category` | enum | Document type | "reference" |
+| `version` | semver | x.y.z — bump on every update | "1.2.0" |
+| `updated` | date | YYYY-MM-DD of last change | "2026-03-18" |
+
+## Category Values
+
+| Value | Purpose |
+|---|---|
+| `reference` | Look-up table, cheat sheet, technical spec |
+| `guide` | Step-by-step how-to documentation |
+| `architecture` | System design and component overview |
+| `api` | API contracts, interfaces, schemas |
+| `plan` | Implementation plan or roadmap |
+| `overview` | Summary introduction to a subsystem |
+
+## Optional Fields
+
+### source_of_truth_for
+A list of glob patterns (fnmatch syntax) pointing to the source files this doc describes. Used by `drift_detector.py` and `doc_structure_analyzer.py` to detect when the source changed but the doc wasn't updated.
+
+```yaml
+source_of_truth_for:
+  - "hooks/**/*.mjs"
+  - "policies/*.json"
+  - "config/pi/extensions/**/*.ts"
+```
+
+### domain
+Tags for cross-cutting concerns. Useful for searching related docs.
+
+```yaml
+domain: [hooks, claude, pi, enforcement]
+```
+
+## Version Bumping Rules
+
+| Change | Bump |
+|---|---|
+| Fix a typo or outdated detail | `patch` (1.0.0 → 1.0.1) |
+| Add a new section | `minor` (1.0.0 → 1.1.0) |
+| Full rewrite or restructure | `major` (1.0.0 → 2.0.0) |
+
+Always update `updated:` to today's date alongside the version bump.
+
+## INDEX Block
+
+`validate_doc.py` auto-generates a navigation table from `##` headings:
+
+```markdown
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+| [Overview](#overview) | ... |
+| [Hook Events](#hook-events) | ... |
+<!-- END INDEX -->
+```
+
+This block is regenerated every time `validate_doc.py` runs on the file. Do not edit it manually.
+
+## Complete Example
+
+```yaml
+---
+title: Hooks Reference
+scope: hooks
+category: reference
+version: 1.1.0
+updated: 2026-03-18
+description: "All hook events, scripts, and behavior for the xtrm plugin"
+source_of_truth_for:
+  - "hooks/**/*.mjs"
+  - "policies/beads.json"
+  - "policies/main-guard.json"
+domain: [hooks, claude, enforcement]
+---
+```