xtrm-tools 2.4.0 → 2.4.2

package/skills/scoping-service-skills/scripts/scope.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+scope.py — Read service-registry.json and output a formatted service catalog.
+
+Used by the /scope skill to provide registry data for agent reasoning before
+any files are touched. The agent uses this output to map a task description
+to the relevant registered service(s).
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def find_registry() -> Path | None:
+    # 1. CLAUDE_PROJECT_DIR env var (set by Claude Code hooks)
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if project_dir:
+        p = Path(project_dir) / ".claude" / "skills" / "service-registry.json"
+        if p.exists():
+            return p
+
+    # 2. Walk up from CWD until .git boundary
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        p = parent / ".claude" / "skills" / "service-registry.json"
+        if p.exists():
+            return p
+        if (parent / ".git").exists():
+            break
+
+    return None
+
+
+def main() -> None:
+    registry_path = find_registry()
+
+    if not registry_path:
+        print("ERROR: service-registry.json not found.")
+        print("Run /creating-service-skills to set up service skills first.")
+        sys.exit(1)
+
+    try:
+        with open(registry_path, encoding="utf-8") as f:
+            registry = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"ERROR: service-registry.json is malformed: {e}")
+        sys.exit(1)
+
+    services = registry.get("services", {})
+    if not services:
+        print("Registry is empty — no services registered.")
+        sys.exit(0)
+
+    print(f"Registry  : {registry_path}")
+    print(f"Version   : {registry.get('version', 'unknown')}")
+    print(f"Services  : {len(services)} registered")
+    print("─" * 60)
+
+    for service_id, info in services.items():
+        territories = ", ".join(info.get("territory", [])) or "—"
+        print(f"\n[{service_id}]")
+        print(f"  Container  : {info.get('container', 'unknown')}")
+        print(f"  Territory  : {territories}")
+        print(f"  Skill      : {info.get('skill_path', 'unknown')}")
+        print(f"  Description: {info.get('description', '—')}")
+
+    print("\n" + "─" * 60)
+    print("Map the task description to the service(s) above, then load their skills.")
+
+
+if __name__ == "__main__":
+    main()

package/skills/sync-docs/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: sync-docs
+description: >-
+  Doc audit and structural sync for xtrm projects. Use whenever the README
+  feels too long, docs are out of sync after a sprint, the CHANGELOG is behind,
+  or the user asks to "sync docs", "doc audit", "split readme", "check docs
+  health", or "detect drift". Also triggers after closing bd issues or merging
+  PRs when documentation cleanup is implied. Reads bd issues, PRs, and memories
+  to understand what changed, then runs drift detection on README.md,
+  CHANGELOG.md, and docs/ — creating missing focused files instead of a
+  monolithic README. Prefer over /documenting for any structural reorganization
+  or multi-file sync work.
+gemini-command: sync-docs
+version: 1.0.0
+---
+
+# sync-docs
+
+Keeps documentation in sync with reality. Reads what was done (bd issues, PRs, memories), finds what's stale or structurally wrong, and fixes it with Serena precision.
+
+## Overview
+
+```
+Phase 1: Gather context     — what was done recently?
+Phase 2: Detect drift       — what's stale in SSOT memories?
+Phase 3: Analyze structure  — what's in the wrong place?
+Phase 4: Plan + execute     — fix with Serena  (SKIP if audit/read-only task)
+Phase 5: Validate           — schema-check all docs/
+```
+
+**Audit vs Execute mode:** If the user asked for an audit, report, or "just check", stop after Phase 3 — do not run `--fix` or edit any files. Only proceed to Phase 4 when the user explicitly wants changes made.
+
+---
+
+## MANDATORY FIRST STEP
+
+Activate the Serena project before any file edits:
+
+```javascript
+mcp__serena__activate_project({ project: "<cwd>" })
+```
+
+---
+
+## Phase 1: Gather Context
+
+```bash
+# If skill is installed globally:
+python3 "$HOME/.claude/skills/sync-docs/scripts/context_gatherer.py" [--since=30]
+
+# If running from the repo directly:
+python3 "skills/sync-docs/scripts/context_gatherer.py" [--since=30]
+```
+
+Outputs a JSON report with:
+- Recently closed bd issues (id, title, closed date)
+- Merged PRs (subject, merge date) from git history
+- bd memories persisted this cycle (`bd memory list` if available)
+- Stale Serena memories (delegates to drift_detector.py)
+
+If no `.beads/` directory exists, falls back to git-only context. All output is JSON — read it and keep the key findings in mind for Phase 3.
+
+---
+
+## Phase 2: Detect SSOT Drift
+
+```bash
+python3 "$HOME/.claude/skills/documenting/scripts/drift_detector.py" scan
+```
+
+This checks which Serena memories have `tracks:` globs matching recently modified files. If something is stale, note the memory name. You will handle it in Phase 4 using the same update steps as `/documenting` — but with Serena tools (not Edit/Write).
+
+> **Note:** `drift_detector.py` requires `pyyaml`. If you see `ModuleNotFoundError: No module named 'yaml'`, skip Phase 2 and note it — the rest of the skill works without it. Do not `pip install` unless the user explicitly approves.
+
+---
+
+## Phase 3: Analyze Document Structure
+
+```bash
+# Analysis only (no changes) — always safe to run:
+python3 "$HOME/.claude/skills/sync-docs/scripts/doc_structure_analyzer.py"
+# or from repo: python3 "skills/sync-docs/scripts/doc_structure_analyzer.py"
+```
+
+Checks:
+1. **README.md bloat** — flags if > 200 lines or contains sections that belong in `docs/`
+2. **CHANGELOG.md coverage** — date gap AND version gap (package.json vs latest changelog entry)
+3. **docs/ gaps** — expected focused files that don't exist yet
+4. **Schema validity** — existing docs/ files missing YAML frontmatter
+
+Reports are categorized as `BLOATED`, `EXTRACTABLE`, `MISSING`, `STALE`, `INVALID_SCHEMA`, or `OK`.
+
+**If the task is audit/analysis only → stop here.** Summarize findings and present to the user. Do not run `--fix` without explicit intent to make changes.
+
+Read `references/doc-structure.md` for the complete guide on what belongs in each docs/ file.
+
+---
+
+## Phase 4: Decide and Execute
+
+| Situation | Action |
+|---|---|
+| README bloated + section belongs in docs/ | Extract → new `docs/X.md`, replace with summary + link |
+| docs/ file missing for existing subsystem | Create `docs/X.md` with schema frontmatter |
+| Serena memory stale | Update memory using Serena tools (see below) |
+| bd issue closed, no doc reflects it | Update CHANGELOG + relevant doc |
+| docs/ file schema invalid | Fix frontmatter, regenerate INDEX |
+| Everything clean | Report "All docs in sync" and stop |
+
+### Editing with Serena (required for all doc edits)
+
+Never use the raw `Edit` tool on documentation files. Always go through Serena:
+
+```javascript
+// 1. Map structure first
+mcp__serena__get_symbols_overview({ relative_path: "README.md", depth: 1 })
+
+// 2. Read only the relevant section
+mcp__serena__find_symbol({ name: "Section Name", include_body: true })
+
+// 3. Replace section content
+mcp__serena__replace_symbol_body({ symbol_name: "Section Name", new_body: "..." })
+
+// 4. Insert a new section after an existing one
+mcp__serena__insert_after_symbol({ symbol_name: "Existing Section", new_symbol: "..." })
+```
+
+The reason this matters: Serena edits are atomic and reference-safe. Direct edits on large markdown files risk corrupting heading structure or inserting duplicates.
+
+### Auto-scaffolding missing docs/ files (--fix)
+
+For known subsystem patterns (hooks/, policies/, skills/, etc.), run `--fix` to generate all missing scaffolds at once:
+
+```bash
+python3 "$HOME/.claude/skills/sync-docs/scripts/doc_structure_analyzer.py" --fix
+```
+
+Combine with `--bd-remember` to persist a summary insight for future sessions:
+
+```bash
+python3 "$HOME/.claude/skills/sync-docs/scripts/doc_structure_analyzer.py" --fix --bd-remember
+```
+
+`--fix` only handles known MISSING patterns. README extraction (BLOATED/EXTRACTABLE) still requires Serena — content judgment is needed to split correctly.
+
+### Creating a single docs/ file manually
+
+Generate the scaffold with valid frontmatter:
+
+```bash
+python3 "$HOME/.claude/skills/sync-docs/scripts/validate_doc.py" --generate docs/hooks.md \
+  --title "Hooks Reference" --scope "hooks" --category "reference" \
+  --source-for "hooks/**/*.mjs,policies/*.json"
+```
+
+Then fill content using Serena. See `references/schema.md` for all frontmatter fields.
+
+### Updating Serena memories (when drift detected)
+
+1. Read the `<!-- INDEX -->` block only — identify stale sections
+2. Use `mcp__serena__search_for_pattern` to jump to stale content
+3. Use `mcp__serena__replace_symbol_body` to update
+4. Bump `version:` (patch = content fix, minor = new section) and `updated:` in frontmatter
+5. Regenerate INDEX:
+
+```bash
+python3 "$HOME/.claude/skills/documenting/scripts/validate_metadata.py" <memory-file>
+```
+
+### Updating CHANGELOG
+
+```bash
+python3 "$HOME/.claude/skills/documenting/scripts/changelog/add_entry.py" \
+  CHANGELOG.md <type> "<summary>"
+```
+
+Types: `Added`, `Changed`, `Fixed`, `Removed`.
+
+### Persisting insights via bd remember
+
+After significant doc work (new docs/ files created, README reorganized, major drift fixed), persist a summary for future sessions:
+
+```bash
+bd remember "<what was done and why>" --key sync-docs-<scope>-<YYYY-MM-DD>
+```
+
+Examples:
+```bash
+bd remember "docs/hooks.md created — extracted from README section + 12 hook scripts cataloged" --key sync-docs-hooks-2026-03-18
+bd remember "README trimmed from 340 to 180 lines — policies, hooks, MCP moved to docs/" --key sync-docs-readme-trim-2026-03-18
+```
+
+This is done automatically when using `--fix --bd-remember`, but do it manually too when making structural changes via Serena.
+
+---
+
+## Phase 5: Validate
+
+Run schema validation on all docs/ files before finishing:
+
+```bash
+python3 "$HOME/.claude/skills/sync-docs/scripts/validate_doc.py" docs/
+```
+
+Exits 0 if all pass. Fix any errors before reporting completion.
+
+---
+
+## Standard docs/ Structure
+
+See `references/doc-structure.md` for the complete guide. At minimum, a mature xtrm project should have:
+
+```
+docs/
+├── hooks.md              # Hook events, scripts, and their behavior
+├── pi-extensions.md      # Pi/Copilot extension catalog
+├── architecture.md       # System design, key components
+└── plans/                # In-progress and completed work plans
+```
+
+If any of these are missing and the project has the relevant code, create them.
+
+---
+
+## Relationship to /documenting
+
+| Use `/sync-docs` when | Use `/documenting` when |
+|---|---|
+| Finishing a feature cycle | Just adding a CHANGELOG entry |
+| README feels too big | Creating a single Serena memory |
+| After merging multiple PRs | Updating one stale memory |
+| Need bd context to know what changed | The scope is already clear |
+| Structural reorganization needed | No structural changes needed |
+
+`/documenting` inherits the changelog scripts from this skill. Both can run in the same repo — they don't conflict.

package/skills/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, identifies EXTRACTABLE/BLOATED sections with specific suggestions for what goes in which docs/ file, and uses Serena to map README structure 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/skills/sync-docs/references/doc-structure.md

@@ -0,0 +1,104 @@
+# docs/ Structure Guide
+
+This reference defines what belongs in each focused docs/ file vs README.md and `.serena/memories/`.
+
+## 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
+
+**.serena/memories/** holds internal AI memory — architecture decisions, patterns, workflows — for the AI agents themselves. These are not user docs.
+
+---
+
+## 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 |
+| Architecture decisions (AI) | `.serena/memories/*_ssot.md` | For AI context only |
+| Implementation patterns (AI) | `.serena/memories/*_pattern.md` | For AI context only |
+
+---
+
+## 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. Run `mcp__serena__get_symbols_overview` on README.md to map all sections
+2. Use `mcp__serena__find_symbol` to read the target section body
+3. Create `docs/X.md` with `validate_doc.py --generate`
+4. Paste the section content into the new file
+5. Use `mcp__serena__replace_symbol_body` to replace README section with:
+   ```markdown
+   See [docs/X.md](docs/X.md) for the full reference.
+   ```
+6. Run `validate_doc.py docs/X.md` to confirm schema

package/skills/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]
+---
+```