specrails-desktop 2.0.0

package/.claude/commands/specrails/memory-inspect.md

@@ -0,0 +1,259 @@
+---
+name: "Agent Memory Inspector"
+description: "Inspect and manage agent memory directories. Lists all sr-* agent memory stores, shows per-agent stats (file count, size, last modified), displays recent entries, and detects stale or orphaned files."
+category: Workflow
+tags: [workflow, memory, agents, maintenance, diagnostics]
+---
+
+Inspect agent memory directories under `.claude/agent-memory/sr-*/` for **specrails-desktop**. Show per-agent stats, recent entries, and actionable recommendations.
+
+**Input:** `$ARGUMENTS` — optional:
+- `<agent-name>` — inspect a specific agent's memory (e.g. `sr-developer`, `sr-reviewer`)
+- `--stale <days>` — flag files not modified in more than N days as stale (default: 30)
+- `--prune` — delete stale files after confirmation (prints the list first, then asks)
+
+---
+
+## Phase 0: Argument Parsing
+
+Parse `$ARGUMENTS` to set runtime variables.
+
+**Variables to set:**
+
+- `AGENT_FILTER` — string or empty string. Default: `""` (inspect all agents).
+- `STALE_DAYS` — integer. Default: `30`.
+- `PRUNE_MODE` — boolean. Default: `false`.
+
+**Parsing rules:**
+
+1. Scan `$ARGUMENTS` for `--stale <N>`. If found, set `STALE_DAYS=<N>`. Validate that `<N>` is a positive integer; if not, print `Error: --stale requires a positive integer (e.g. --stale 14)` and stop. Strip from arguments.
+2. Scan for `--prune`. If found, set `PRUNE_MODE=true`. Strip from arguments.
+3. Remaining non-flag text (if any) is treated as `AGENT_FILTER`. Strip leading/trailing whitespace.
+
+**Print active configuration:**
+
+```
+Scanning: <all agents | agent: AGENT_FILTER> | Stale threshold: STALE_DAYS days | Prune: yes/no
+```
+
+---
+
+## Phase 1: Discover Memory Directories
+
+Glob all directories matching `.claude/agent-memory/sr-*/`.
+
+If no directories are found:
+```
+No agent memory directories found under .claude/agent-memory/.
+
+Agent memory is written by sr-* agents during the /specrails:implement pipeline.
+Run /specrails:implement on a feature to generate your first memory entries.
+```
+Then stop.
+
+If `AGENT_FILTER` is set, filter to only the directory `.claude/agent-memory/<AGENT_FILTER>/`. If that directory does not exist:
+```
+No memory directory found for agent: <AGENT_FILTER>
+
+Available agents:
+  <list of discovered sr-* directory names>
+```
+Then stop.
+
+Set `AGENT_DIRS` = list of matching directories (full paths), sorted alphabetically.
+
+---
+
+## Phase 2: Collect Per-Agent Stats
+
+For each directory in `AGENT_DIRS`, collect:
+
+- `AGENT_NAME` — directory name (e.g. `sr-developer`)
+- `FILE_COUNT` — total number of files (recursive, all types)
+- `TOTAL_SIZE` — total size in bytes; display as human-readable (KB, MB)
+- `LAST_MODIFIED` — ISO date of the most recently modified file
+- `OLDEST_MODIFIED` — ISO date of the least recently modified file
+- `STALE_FILES` — list of files not modified in more than `STALE_DAYS` days (full paths)
+- `STALE_COUNT` — count of stale files
+
+Use the current date to compute stale age. A file is stale if `(today - last_modified) > STALE_DAYS`.
+
+Print a summary table after collecting all stats:
+
+```
+## Agent Memory Overview
+
+| Agent | Files | Size | Last Modified | Stale (>STALE_DAYS days) |
+|-------|-------|------|---------------|--------------------------|
+| sr-developer   | N | N KB | YYYY-MM-DD | N files |
+| sr-reviewer    | N | N KB | YYYY-MM-DD | N files |
+| ...            | ... | ... | ...        | ...     |
+
+Total: N agents | N files | N KB
+```
+
+---
+
+## Phase 3: Display Recent Entries
+
+For each agent in `AGENT_DIRS`, show the 5 most recently modified files.
+
+Print per agent:
+
+```
+### <agent-name>
+
+Recent entries (5 most recent):
+
+| File | Size | Last Modified |
+|------|------|---------------|
+| common-fixes.md | 2.1 KB | 2026-03-18 |
+| ...             | ...    | ...         |
+```
+
+If the agent directory has fewer than 5 files, show all of them.
+
+If `AGENT_FILTER` is set (single-agent mode), show the full content of each file up to 50 lines. For files exceeding 50 lines, print the first 50 lines followed by:
+```
+... (N more lines — view full file at <relative-path>)
+```
+
+---
+
+## Phase 4: Orphan Detection
+
+An **orphaned** memory directory is one whose agent name does not correspond to a known sr-agent persona.
+
+Known sr-agent names (check for exact match):
+`sr-architect`, `sr-developer`, `sr-test-writer`, `sr-reviewer`, `sr-frontend-reviewer`, `sr-backend-reviewer`, `sr-security-reviewer`, `sr-doc-sync`, `sr-product-manager`
+
+For each directory in `AGENT_DIRS`, check whether its `AGENT_NAME` is in the known list. Collect non-matching directories as `ORPHANED_DIRS`.
+
+If `ORPHANED_DIRS` is non-empty, print:
+
+```
+### Orphaned Memory Directories
+
+The following directories do not match any known sr-agent name and may be leftover from renamed or removed agents:
+
+| Directory | Files | Size | Recommendation |
+|-----------|-------|------|----------------|
+| sr-old-agent | N | N KB | Review and delete if no longer needed |
+```
+
+If `ORPHANED_DIRS` is empty: skip this section entirely.
+
+---
+
+## Phase 5: Stale File Report
+
+Collect all stale files across all agents (from Phase 2 `STALE_FILES` lists).
+
+If no stale files exist:
+```
+No stale files found (threshold: STALE_DAYS days). Memory is up to date.
+```
+Skip the rest of Phase 5.
+
+Otherwise, print:
+
+```
+### Stale Files (not modified in >STALE_DAYS days)
+
+| Agent | File | Size | Last Modified | Age (days) |
+|-------|------|------|---------------|------------|
+| sr-developer | common-fixes.md | 1.2 KB | 2026-01-10 | 69 |
+| ...          | ...             | ...    | ...        | ...        |
+
+N stale files total (N KB).
+```
+
+---
+
+## Phase 6: Prune (if --prune)
+
+Skip this phase if `PRUNE_MODE=false`.
+
+If `PRUNE_MODE=true` and there are no stale files and no orphaned directories:
+```
+Nothing to prune. All memory files are within the STALE_DAYS-day threshold.
+```
+Then stop.
+
+Otherwise, print the full list of files and directories that will be deleted:
+
+```
+## Files to Delete
+
+The following N files will be permanently deleted:
+
+Stale files:
+  - .claude/agent-memory/sr-developer/common-fixes.md (69 days old)
+  - ...
+
+Orphaned directories:
+  - .claude/agent-memory/sr-old-agent/ (N files, N KB)
+
+Proceed? [y/N]:
+```
+
+Wait for user input.
+
+- If the user enters `y` or `Y`:
+  - Delete each stale file individually.
+  - Delete each orphaned directory recursively.
+  - Print a confirmation for each deletion: `Deleted: <path>`
+  - Print a summary:
+    ```
+    Pruned N files (N KB freed).
+    ```
+- If the user enters anything else (or presses Enter):
+  - Print: `Prune cancelled. No files were deleted.`
+  - Stop.
+
+---
+
+## Phase 7: Recommendations
+
+Print a final recommendations section based on findings:
+
+```
+## Recommendations
+
+<one or more of the following, based on findings>
+```
+
+**Recommendation rules (print only applicable ones):**
+
+1. **Prune stale data** — if `STALE_COUNT > 0` across any agent and `PRUNE_MODE=false`:
+   ```
+   - N stale files detected. Run `/specrails:memory-inspect --prune` to remove them and free N KB.
+   ```
+
+2. **Investigate large memory** — if any single agent's `TOTAL_SIZE > 1 MB`:
+   ```
+   - <agent-name> memory exceeds 1 MB (TOTAL_SIZE). Consider reviewing large files:
+     <list files over 100 KB>
+   ```
+
+3. **Orphaned directories** — if `ORPHANED_DIRS` is non-empty:
+   ```
+   - N orphaned director(y|ies) found. Review and delete manually if no longer needed.
+   ```
+
+4. **Empty memory directories** — if any agent directory has `FILE_COUNT = 0`:
+   ```
+   - <agent-name> memory directory is empty. It may be safe to delete:
+     rm -rf .claude/agent-memory/<agent-name>/
+   ```
+
+5. **Gitignore advisory** — check whether `.claude/agent-memory` appears in `.gitignore`. If not:
+   ```
+   - Agent memory is local runtime state. Add to .gitignore:
+       echo '.claude/agent-memory/' >> .gitignore
+   ```
+
+If no recommendations apply, print:
+```
+All agent memory looks healthy. No action required.
+```

package/.claude/commands/specrails/opsx-diff.md

@@ -0,0 +1,419 @@
+---
+name: "OpenSpec Change Diff Visualizer"
+description: "Show a before/after diff of OpenSpec spec changes for a given change. Highlights additions, removals, and behavioral modifications across acceptance criteria, flows, and constraints. Supports markdown and JSON output."
+category: Workflow
+tags: [openspec, diff, specs, visualization, changes]
+---
+
+Visualize spec changes for **specrails-desktop**: compare the current specs against a named OpenSpec change to show exactly what behavioral requirements are being added, modified, or removed.
+
+**Input:** $ARGUMENTS — accepts:
+- `<change-name>` — the kebab-case name of the change to diff (required). If omitted, interactive selection is offered.
+- `--format json` — emit structured JSON instead of markdown (default: markdown).
+- `--summary-only` — skip inline line-level diff; show only the file-level and behavioral summary.
+
+---
+
+## Phase 0: Argument Parsing
+
+Parse `$ARGUMENTS` to set runtime variables.
+
+**Variables to set:**
+
+- `CHANGE_NAME` — string. Required. If not provided, prompt the user.
+- `FORMAT` — `"markdown"` or `"json"`. Default: `"markdown"`.
+- `SUMMARY_ONLY` — boolean. Default: `false`.
+
+**Parsing rules:**
+
+1. Scan `$ARGUMENTS` for `--format <value>`. If found and value is `json`, set `FORMAT="json"`. Any other value: print `Error: unknown format "<value>". Valid: markdown, json` and stop. Strip from arguments.
+2. Scan for `--summary-only`. If found, set `SUMMARY_ONLY=true`. Strip from arguments.
+3. Treat the remaining token (if any) as `CHANGE_NAME`. Strip leading/trailing whitespace.
+4. If `CHANGE_NAME` is empty after parsing:
+   - Run:
+     ```bash
+     openspec list --json
+     ```
+   - If the result shows available changes, use the **AskUserQuestion tool** (open-ended, show the list) to ask which change to diff.
+   - If no changes exist, print:
+     ```
+     Error: no active changes found. Run /opsx:new or /opsx:ff to create one first.
+     ```
+     Stop.
+
+**Print active configuration:**
+
+```
+Diffing change: <CHANGE_NAME>
+Format: <markdown|json>
+Summary only: <yes|no>
+```
+
+---
+
+## Phase 1: Locate the Change
+
+Find the change directory and enumerate its spec artifacts.
+
+### Step 1a: Resolve the change path
+
+Check these locations in order:
+
+1. `openspec/changes/<CHANGE_NAME>/` — active change.
+2. `openspec/changes/archive/` — glob for directories matching `*<CHANGE_NAME>` or exact `<CHANGE_NAME>`. Take the most recent match (latest date prefix).
+
+If neither location yields a directory, print:
+
+```
+Error: change "<CHANGE_NAME>" not found.
+Searched:
+  - openspec/changes/<CHANGE_NAME>/
+  - openspec/changes/archive/*<CHANGE_NAME>*/
+
+Run `openspec list` to see available changes.
+```
+
+Stop.
+
+Set `CHANGE_DIR` to the resolved path.
+
+**Print:** `Found change at: <CHANGE_DIR>`
+
+### Step 1b: Enumerate spec artifacts in the change
+
+Collect spec content from the change directory using this priority:
+
+1. **Delta-spec file** — `<CHANGE_DIR>/delta-spec.md`. If present, read it. Set `HAS_DELTA_SPEC=true`.
+2. **Inline specs subdirectory** — `<CHANGE_DIR>/specs/`. If present, glob `**/*.md` within it. Each file is an individual spec. Set `HAS_SPEC_DIR=true`.
+3. **Proposal file** — `<CHANGE_DIR>/proposal.md`. Always read if present. Used for context but not as a primary diff source. Set `HAS_PROPOSAL=true`.
+
+At least one of `HAS_DELTA_SPEC` or `HAS_SPEC_DIR` must be true to proceed.
+
+If neither exists:
+```
+Warning: no spec artifacts found in <CHANGE_DIR>.
+  Expected: delta-spec.md or specs/*.md
+
+The change may not have reached the spec authoring phase yet.
+Run /opsx:continue to create specs first.
+```
+Stop.
+
+Store the collected spec content:
+- `DELTA_SPEC` — string content of delta-spec.md (or `""` if absent).
+- `CHANGE_SPECS` — array of `{ path, content }` objects from the specs/ subdirectory (or `[]` if absent).
+- `PROPOSAL` — string content of proposal.md (or `""` if absent).
+
+**Print:** `Spec artifacts: <delta-spec.md present|absent>, <N spec files in specs/>, proposal <present|absent>`
+
+---
+
+## Phase 2: Load Baseline Specs
+
+Find the current baseline specs to compare against.
+
+### Step 2a: Discover baseline spec files
+
+Glob for markdown files in `openspec/specs/` (recursively: `openspec/specs/**/*.md`).
+
+Store as `BASELINE_SPECS` — array of `{ path, content }` objects.
+
+If `openspec/specs/` does not exist or contains no files:
+```
+Note: no baseline specs found in openspec/specs/.
+Diff will show all change specs as net-new additions (no removals or modifications).
+```
+Set `BASELINE_SPECS=[]`.
+
+**Print:** `Baseline: <N> spec file(s) found in openspec/specs/`
+
+### Step 2b: Match change specs to baseline specs
+
+For each entry in `CHANGE_SPECS` (from the change's specs/ subdirectory), attempt to find its counterpart in `BASELINE_SPECS`.
+
+**Matching rule:** A change spec at `<CHANGE_DIR>/specs/<spec-name>/spec.md` matches a baseline spec at `openspec/specs/<spec-name>/spec.md` or `openspec/specs/<spec-name>.md`. Match on the spec name segment only.
+
+Build `SPEC_PAIRS` — array of:
+```
+{
+  specName: string,
+  changePath: string | null,       // path in change (null if baseline-only)
+  baselinePath: string | null,     // path in baseline (null if change-only)
+  changeContent: string | null,
+  baselineContent: string | null,
+  matchType: "new" | "modified" | "deleted" | "unchanged"
+}
+```
+
+**Match type rules:**
+- `changePath` present, `baselinePath` absent → `"new"`.
+- `changePath` absent, `baselinePath` present (and baseline spec is referenced/affected by delta-spec) → `"deleted"`.
+- Both present and content differs → `"modified"`.
+- Both present and content identical → `"unchanged"`.
+
+For the delta-spec flow (when `HAS_DELTA_SPEC=true` and `HAS_SPEC_DIR=false`):
+- The delta-spec itself is the primary artifact. There is no per-file pairing.
+- Set `SPEC_PAIRS=[]` and use the delta-spec content directly in Phase 3.
+
+---
+
+## Phase 3: Compute the Diff
+
+Produce a structured diff comparing baseline vs. change specs.
+
+### Step 3a: Delta-spec analysis (when HAS_DELTA_SPEC=true)
+
+Parse the delta-spec sections to extract behavioral elements:
+
+**Acceptance criteria / SHALL statements:**
+- Glob for lines matching the pattern: `^\*\*\d+\.\d+\*\*` (numbered normative statements like `**1.1**`).
+- Collect all `{ id, text }` pairs into `DELTA_STATEMENTS`.
+
+**Surface impact table:**
+- Find the `## Surface Impact` section (or `### Surface Impact of This Change`).
+- Parse all table rows into `SURFACE_CHANGES`: `[ { category, element, change, severity } ]`.
+
+**REST/API contract changes:**
+- Find any section with "REST API", "API Contract", or "Endpoints" in the heading.
+- Extract endpoint definitions: method + path + response shape changes.
+- Store as `API_CHANGES`.
+
+**Since there is no true baseline for a delta-spec** (it defines net-new behavior), classify every `DELTA_STATEMENTS` entry as a `"new"` addition. If the "Surface Impact" table includes rows with change type "Removal" or "BREAKING", classify those as `"modified"` or `"deleted"` accordingly.
+
+Build `DIFF_RESULT`:
+```
+{
+  addedStatements: [{ id, text }],
+  modifiedStatements: [{ id, text, changeDescription }],
+  removedStatements: [{ id, text }],
+  surfaceChanges: [{ category, element, change, severity }],
+  apiChanges: [{ method, path, description }],
+  specPairs: []
+}
+```
+
+### Step 3b: Spec-file-pair analysis (when HAS_SPEC_DIR=true)
+
+For each `SPEC_PAIR` in `SPEC_PAIRS` where `matchType !== "unchanged"`:
+
+**Line-level diff:**
+
+Compare `baselineContent` and `changeContent` line by line:
+
+1. Split each content string into lines.
+2. Identify added lines (present in change, absent in baseline) and removed lines (present in baseline, absent in change).
+3. For each changed block, compute a ±3-line context window.
+4. Mark heading lines (starting with `#`) separately — heading changes indicate structural reorganization.
+5. Mark lines containing normative language (`SHALL`, `MUST`, `SHOULD`, `MAY`, `SHALL NOT`, `MUST NOT`) as behavioral.
+
+Produce `{ specName, matchType, addedLines, removedLines, behavioralChanges, headingChanges }`.
+
+**Behavioral change classification:**
+
+- Line added + contains `SHALL`/`MUST` → new requirement.
+- Line removed + contains `SHALL`/`MUST` → removed requirement.
+- Line modified (matched by proximity) + normative keyword → modified requirement.
+- Other additions/removals → structural/non-normative.
+
+Build `DIFF_RESULT` from all `SPEC_PAIRS`.
+
+### Step 3c: Compute summary statistics
+
+```
+ADDED_COUNT    = count(addedStatements) + count(added spec files)
+MODIFIED_COUNT = count(modifiedStatements) + count(modified spec files)
+REMOVED_COUNT  = count(removedStatements) + count(deleted spec files)
+TOTAL_CHANGES  = ADDED_COUNT + MODIFIED_COUNT + REMOVED_COUNT
+```
+
+---
+
+## Phase 4: Render Output
+
+### If FORMAT = "json"
+
+Emit a single JSON object:
+
+```json
+{
+  "schema_version": "1",
+  "project": "specrails-desktop",
+  "change": "<CHANGE_NAME>",
+  "generated_at": "<ISO 8601 timestamp>",
+  "source": "<delta-spec | spec-files>",
+  "summary": {
+    "total_changes": <N>,
+    "added": <N>,
+    "modified": <N>,
+    "removed": <N>
+  },
+  "added_statements": [
+    { "id": "1.1", "text": "..." }
+  ],
+  "modified_statements": [
+    { "id": "2.3", "text": "...", "change_description": "..." }
+  ],
+  "removed_statements": [
+    { "id": "3.1", "text": "..." }
+  ],
+  "surface_changes": [
+    { "category": "...", "element": "...", "change": "...", "severity": "..." }
+  ],
+  "api_changes": [
+    { "method": "POST", "path": "/api/spawn", "description": "..." }
+  ],
+  "spec_pairs": [
+    {
+      "spec_name": "...",
+      "match_type": "new|modified|deleted",
+      "added_lines": ["..."],
+      "removed_lines": ["..."],
+      "behavioral_changes": ["..."],
+      "heading_changes": ["..."]
+    }
+  ]
+}
+```
+
+Stop after emitting JSON.
+
+### If FORMAT = "markdown"
+
+Render the full diff report:
+
+```
+## OpenSpec Change Diff — <CHANGE_NAME>
+Project: specrails-desktop | Generated: <YYYY-MM-DD HH:MM>
+
+### Summary
+
+| Metric | Count |
+|--------|-------|
+| ➕ Added requirements | <N> |
+| ✏️  Modified requirements | <N> |
+| ➖ Removed requirements | <N> |
+| **Total changes** | **<N>** |
+```
+
+**If TOTAL_CHANGES = 0:**
+```
+✅ No behavioral differences detected between the change specs and the baseline.
+```
+Stop.
+
+---
+
+Then render sections:
+
+#### Added Requirements
+
+```
+### ➕ Added Requirements (<N>)
+
+<for each added statement:>
+> **<id>** <text>
+
+<if none:>
+_No new requirements._
+```
+
+#### Modified Requirements
+
+```
+### ✏️  Modified Requirements (<N>)
+
+<for each modified statement or spec pair with matchType="modified":>
+#### <spec-name or section heading>
+
+\`\`\`diff
+- <removed line>
++ <added line>
+\`\`\`
+
+**Change:** <change_description or inferred summary>
+
+<if SUMMARY_ONLY=true: skip inline diff blocks, show only change description>
+```
+
+#### Removed Requirements
+
+```
+### ➖ Removed Requirements (<N>)
+
+<for each removed statement:>
+> ~~**<id>** <text>~~
+
+<if none:>
+_No requirements removed._
+```
+
+#### Surface Impact (when HAS_DELTA_SPEC=true and SURFACE_CHANGES is non-empty)
+
+```
+### 🗺️  Surface Impact
+
+| # | Category | Element | Change | Severity |
+|---|----------|---------|--------|----------|
+<rows from SURFACE_CHANGES>
+```
+
+#### API Contract Changes (when API_CHANGES is non-empty)
+
+```
+### 🔌 API Contract Changes
+
+<for each API_CHANGES entry:>
+- **<METHOD> <path>** — <description>
+```
+
+#### New Spec Files (when added spec files exist)
+
+```
+### 📄 New Spec Files
+
+<for each specPair where matchType="new":>
+- `<changePath>` — new spec, no baseline counterpart
+```
+
+#### Deleted Spec Files (when deleted spec files exist)
+
+```
+### 🗑️  Deleted Spec Files
+
+<for each specPair where matchType="deleted":>
+- `<baselinePath>` — removed by this change
+```
+
+---
+
+Close the report:
+
+```
+---
+_Generated by `/specrails:opsx-diff` in specrails-desktop_
+_Change source: <CHANGE_DIR>_
+
+**Next steps:**
+- Run `/opsx:apply <CHANGE_NAME>` to implement these changes.
+- Run `/opsx:archive <CHANGE_NAME>` after implementation to merge specs into baseline.
+```
+
+---
+
+## Phase 5: Save Snapshot (optional)
+
+After rendering, write a diff snapshot to `.claude/opsx-diff-history/`:
+
+1. Filename: `<CHANGE_NAME>-<YYYY-MM-DD>.json`
+2. Directory: `.claude/opsx-diff-history/` (create if absent, idempotent).
+3. Content: the JSON object from Phase 4 (regardless of FORMAT setting).
+
+Print: `Snapshot saved: .claude/opsx-diff-history/<CHANGE_NAME>-<YYYY-MM-DD>.json`
+
+If the write fails: print `Warning: could not write diff snapshot. Continuing.` Do not abort.
+
+**Housekeeping:** If `.claude/opsx-diff-history/` has more than 50 `.json` files, print:
+```
+Note: .claude/opsx-diff-history/ has <N> snapshots. Prune old ones with:
+  ls -t .claude/opsx-diff-history/ | tail -n +51 | xargs -I{} rm .claude/opsx-diff-history/{}
+```