@hir4ta/mneme 0.17.0

package/skills/resume/skill.md

@@ -0,0 +1,278 @@
+---
+name: resume
+description: |
+  Resume a previous session with full context restoration.
+  Use when: (1) continuing work from a previous session, (2) reviewing past session details,
+  (3) picking up where you left off after a break.
+argument-hint: "[session-id]"
+---
+
+# /mneme:resume
+
+Resume a previous session.
+
+## Usage
+
+```
+/mneme:resume              # Show recent sessions
+/mneme:resume <id>         # Resume specific session
+/mneme:resume --type=implementation  # Filter by session type
+/mneme:resume --tag=auth   # Filter by tag
+/mneme:resume --days=7     # Filter by last N days
+/mneme:resume --branch=feature/auth  # Filter by branch
+```
+
+### Filter Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--type=<type>` | Filter by sessionType | `--type=implementation` |
+| `--tag=<tag>` | Filter by tag | `--tag=auth` |
+| `--days=<n>` | Filter by last N days | `--days=7` |
+| `--branch=<name>` | Filter by branch | `--branch=main` |
+
+Multiple filters can be combined:
+```
+/mneme:resume --type=implementation --days=14
+```
+
+### Session Types
+
+| Type | Description |
+|------|-------------|
+| `decision` | Decision cycle present |
+| `implementation` | Code changes made |
+| `research` | Research, learning |
+| `exploration` | Codebase exploration |
+| `discussion` | Discussion only |
+| `debug` | Debugging |
+| `review` | Code review |
+
+## Execution Steps
+
+1. Read all JSON files under `.mneme/sessions/` (including year/month folders)
+2. Apply filters if specified:
+   - `--type`: Match `summary.sessionType` or `sessionType` field
+   - `--tag`: Match any tag in `tags` array
+   - `--days`: Compare `createdAt` with current date
+   - `--branch`: Match `context.branch` field
+3. Sort by `createdAt` descending (most recent first)
+4. Display filtered session list
+5. If session ID specified, read the JSON file and get details
+6. **Create session-link file** (new master session support)
+7. **Update master session JSON with `workPeriods` entry**
+8. **Update current session JSON with `resumedFrom` field** (legacy, for backwards compatibility)
+9. Load session context to resume work
+
+### File Operations
+
+```bash
+# Get session list
+Glob: .mneme/sessions/**/*.json
+
+# Read each session file (metadata)
+Read: .mneme/sessions/{year}/{month}/{filename}.json
+
+# Get interactions from local SQLite (private, project-local)
+# Local DB location: .mneme/local.db
+sqlite3 ".mneme/local.db" "SELECT * FROM interactions WHERE session_id = '{id}' ORDER BY timestamp;"
+
+# Create session-link file (NEW - master session support)
+# This links current Claude session to the master mneme session
+Write: .mneme/session-links/{current_session_short_id}.json
+  → {"masterSessionId": "{resumed_session_id}", "claudeSessionId": "{current_full_session_id}", "linkedAt": "{now}"}
+
+# Update MASTER session with workPeriods entry (NEW)
+Edit: .mneme/sessions/{master_year}/{master_month}/{master_id}.json
+  → Add entry to workPeriods array: {"claudeSessionId": "{current_full_session_id}", "startedAt": "{now}", "endedAt": null}
+
+# Update CURRENT session with resumedFrom (legacy, for backwards compatibility)
+Edit: .mneme/sessions/{current_year}/{current_month}/{current_id}.json
+  → Add "resumedFrom": "{resumed_session_id}"
+
+# Filter logic (pseudo-code)
+for each session:
+  if --type specified and session.summary?.sessionType != type: skip
+  if --tag specified and tag not in session.tags: skip
+  if --days specified and session.createdAt < (now - days): skip
+  if --branch specified and session.context.branch != branch: skip
+```
+
+## Output Format
+
+### List View
+
+```
+Recent sessions (filtered: --type=implementation --days=14):
+
+  1. [abc123] JWT authentication implementation (2026-01-24, feature/auth)
+     Type: implementation
+     Tags: [auth] [jwt] [backend]
+     Interactions: 3
+     Has Summary: Yes
+
+  2. [def456] User management API (2026-01-23, feature/user)
+     Type: implementation
+     Tags: [user] [api]
+     Interactions: 2
+     Has Summary: No
+
+Select a session to resume (1-2), or enter ID:
+```
+
+### Resume View
+
+```
+Resuming session "JWT authentication implementation"
+
+Session chain: current ← abc123
+(Updated current session with resumedFrom: abc123)
+
+---
+
+## Summary:
+
+  Title: JWT authentication implementation
+  Goal: Implement JWT-based auth with refresh token support
+  Outcome: success
+  Type: implementation
+
+## Plan:
+
+  Tasks:
+    - [x] JWT signing method selection
+    - [x] Middleware implementation
+    - [ ] Add tests
+  Remaining:
+    - Add tests
+
+## Discussions:
+
+  - Signing algorithm: RS256 (Security considerations for production)
+
+## Handoff:
+
+  Stopped: Test creation postponed to next session
+  Notes:
+    - vitest configured
+    - Mock key pair in test/fixtures/
+  Next:
+    - Create jwt.test.ts
+    - Add E2E tests
+
+## Errors:
+
+  - secretOrPrivateKey must be asymmetric → Generate RS256 key pair
+
+---
+
+## Interactions Log (from SQLite):
+
+[int-001] 2026-01-24T10:00:00Z
+  User: Implement authentication
+  Thinking: JWT would be better for microservices...
+  Assistant: Implemented JWT auth with RS256 signing
+
+[int-002] 2026-01-24T10:30:00Z
+  User: What should be the refresh token expiry?
+  Thinking: Balance between security and UX...
+  Assistant: Set to 7 days
+
+(Note: If this session was created by another user, interactions won't be available - only metadata from JSON)
+
+---
+
+Ready to continue?
+```
+
+## Context Injection
+
+When resuming, inject context from JSON (metadata) and SQLite (interactions):
+
+### Structured Data (from JSON, set by /mneme:save):
+1. **Summary**: title, goal, outcome, description, sessionType
+2. **Plan**: tasks, remaining → what was planned and what's left
+3. **Discussions**: decisions with reasoning and alternatives
+4. **Code examples**: significant changes with before/after
+5. **Errors**: problems encountered and solutions
+6. **Handoff**: stoppedReason, notes, nextSteps → critical for continuity
+7. **References**: documents and resources used
+
+### Log Data (from JSON, auto-saved by SessionEnd):
+8. **Title/Tags**: For quick context
+9. **Files**: What files were changed
+10. **Metrics**: Message counts, tool usage
+
+### Interactions (from SQLite, auto-saved by SessionEnd):
+11. **Interactions**: Full conversation log with thinking (private, local only)
+
+**Privacy Note**: Interactions are stored in project-local SQLite (`.mneme/local.db`) and are private to each developer.
+If you're resuming a session created by another team member, interactions won't be available.
+
+**Important**:
+- JSON contains metadata (shared via Git)
+- SQLite contains interactions (local, private)
+- Always update the CURRENT session's JSON with `resumedFrom` to track session chains.
+
+## Session Chain Tracking (Master Session Support)
+
+When resuming session `abc123` (master) in a new Claude session `xyz789`:
+
+### Step 1: Create session-link file
+
+```bash
+# Create .mneme/session-links/ directory if not exists
+mkdir -p .mneme/session-links/
+
+# Write session-link file
+Write: .mneme/session-links/xyz78901.json
+```
+
+```json
+{
+  "masterSessionId": "abc12345",
+  "claudeSessionId": "xyz78901-38e9-464d-9b7c-a9cdca203b5e",
+  "linkedAt": "2026-01-27T09:10:00Z"
+}
+```
+
+### Step 2: Update master session workPeriods
+
+```bash
+Edit: .mneme/sessions/{year}/{month}/abc12345.json
+```
+
+Add to `workPeriods` array:
+```json
+{
+  "workPeriods": [
+    {"claudeSessionId": "abc12345-...", "startedAt": "...", "endedAt": "..."},
+    {"claudeSessionId": "xyz78901-...", "startedAt": "2026-01-27T09:10:00Z", "endedAt": null}
+  ]
+}
+```
+
+### Step 3: Update current session (legacy, backwards compatibility)
+
+```bash
+Edit: .mneme/sessions/{year}/{month}/xyz78901.json
+```
+
+```json
+{
+  "id": "xyz78901",
+  "resumedFrom": "abc12345",
+  ...
+}
+```
+
+### Result
+
+- **session-link file**: Links Claude session → mneme master session
+- **workPeriods**: Tracks all work periods in the master session
+- **resumedFrom**: Legacy chain tracking (backwards compatible)
+
+This design allows:
+1. Multiple Claude sessions to contribute to one logical mneme session
+2. `/mneme:save` to merge all data into the master session
+3. Dashboard to show unified conversation history

package/skills/review/skill.md

@@ -0,0 +1,419 @@
+---
+name: review
+description: |
+  Code review based on repository-specific rules (dev-rules.json / review-guidelines.json).
+  Use when: (1) reviewing staged changes before commit, (2) reviewing a GitHub PR,
+  (3) checking code quality against team standards.
+argument-hint: "[--staged|--all|--diff=branch|PR-URL]"
+---
+
+# /mneme:review
+
+Code review based on repository-specific rules (`dev-rules.json` / `review-guidelines.json`).
+
+## Usage
+
+```
+/mneme:review           # Default: --staged (Stage 2 only)
+/mneme:review --staged  # Review staged changes
+/mneme:review --all     # Review all changes
+/mneme:review --diff=main  # Review diff against branch
+/mneme:review --full    # Two-stage review (Stage 1: Spec + Stage 2: Code)
+/mneme:review https://github.com/owner/repo/pull/123  # Review GitHub PR
+```
+
+### Default Behavior
+
+- **`--staged` is default**
+- If staged is empty, suggest `--all` / `--diff=branch`
+
+### PR URL Review
+
+When a GitHub PR URL is provided:
+1. Parse URL to extract owner, repo, and PR number
+2. Fetch PR diff using `gh pr diff {number} --repo {owner}/{repo}`
+3. Apply the same rule-based review as local diffs
+4. Save result with `target.type: "pr"` and `target.prSource`
+
+### Two-Stage Review (--full)
+
+When `--full` is specified, perform two-stage review:
+
+**Stage 1: Spec Compliance** (blocks if fails)
+- Check implementation against plan/design documents
+- Verify all planned tasks were implemented
+- Confirm architecture matches design
+- Must pass before Stage 2
+
+**Stage 2: Code Quality** (standard review)
+- Apply dev-rules.json / review-guidelines.json
+- Check language/framework best practices
+- Generate findings
+
+## Execution
+
+**Recommended**: Use the `mneme-reviewer` subagent for isolated review context:
+
+```typescript
+Task({
+  subagent_type: "mneme-reviewer",
+  prompt: "Review staged changes against mneme rules",
+  description: "Code review"
+})
+```
+
+The subagent has the review skill preloaded and operates with isolated context for focused review.
+
+**Alternative**: Execute steps manually (see below).
+
+## Execution Steps
+
+### PR URL Detection
+
+Before processing flags, check if the argument is a GitHub PR URL:
+```
+Pattern: https://github.com/{owner}/{repo}/pull/{number}
+```
+
+If PR URL detected:
+1. Parse URL → `{ owner, repo, prNumber, url }`
+2. Fetch diff: `gh pr diff {prNumber} --repo {owner}/{repo}`
+3. Skip to step 2 (Load rules)
+4. Save result with PR-specific target format
+
+### Standard Review (default)
+
+1. **Get target diff**
+   - `--staged`: `git diff --staged`
+   - `--all`: `git diff`
+   - `--diff=branch`: `git diff <branch>...HEAD`
+   - PR URL: `gh pr diff {number} --repo {owner}/{repo}`
+2. **Load rules**
+   - `.mneme/rules/dev-rules.json`
+   - `.mneme/rules/review-guidelines.json`
+3. **Filter applicable rules**
+   - Only `status: active`
+   - Filter by `scope / tags / appliesTo / exceptions`
+4. **Generate findings**
+   - Extract where rules match the diff
+   - Determine severity from `priority`
+5. **Output review**
+   - Structure: Blocker / Warning / Suggestion
+6. **Save review result**
+   - `.mneme/reviews/YYYY/MM/review-YYYY-MM-DD_HHMMSS.json`
+
+### Two-Stage Review (--full)
+
+#### Stage 1: Spec Compliance
+
+1. **Find plan/design documents**
+   ```
+   Search for recent files:
+   - docs/plans/*-tasks.md
+   - docs/plans/*-design.md
+   ```
+
+2. **Extract planned items**
+   - Parse task list from tasks.md
+   - Extract architecture/components from design.md
+
+3. **Verify implementation**
+   - Check each planned task has corresponding code
+   - Verify architecture matches design
+   - Confirm all components exist
+
+4. **Generate Stage 1 findings**
+   ```markdown
+   ## Stage 1: Spec Compliance
+
+   **Plan file:** docs/plans/2026-01-27-feature-tasks.md
+   **Design file:** docs/plans/2026-01-27-feature-design.md
+
+   ### Status: PASS / FAIL
+
+   ### Findings
+   - [MISSING] Task 3 not implemented
+   - [MISMATCH] Component X uses different architecture than planned
+   ```
+
+5. **Block if Stage 1 fails**
+   - If any MISSING or MISMATCH findings, stop review
+   - User must fix before Stage 2
+
+#### Stage 2: Code Quality
+
+(Standard review steps 2-6)
+
+## Additional Review Perspectives (Required)
+
+### Document-Code Consistency
+
+- Verify changes match **all documentation**
+- If spec documents exist, **always reference**:
+  - Files/dirs containing `spec` / `requirements` / `design` / `architecture` / `adr` / `decision` / `workflow` / `contract`
+  - Common doc locations: `docs/`, `documentation/`, `design/`, `spec/`, `requirements/`
+  - Root docs: `README*`, `DEVELOPER*`, `ARCHITECTURE*`, `CONTRIBUTING*`, `SPEC*`, `ADR*`
+  - If not found, **ask user for location** before proceeding
+
+### Language/Framework Best Practices
+
+- Check against language/framework conventions for changed files
+- When uncertain, **research official docs** and cite source
+  - e.g., React / TypeScript / Hono / Node official docs
+  - Mark as **"needs investigation"** if uncertain
+
+## Rule Application Guidelines
+
+### scope Determination (from path)
+
+- `dashboard/` → `dashboard`
+- `hooks/` → `hooks`
+- `skills/` → `skills`
+- `dashboard/server/` → `server`
+- `config`/`env`/`tsconfig`/`vite.config` → `config`
+- Other → `general`
+
+### tags Assignment (from path or diff content)
+
+- `ui` (dashboard/react/css)
+- `api` (server/api)
+- `quality` (lint/test/build)
+- `security` (auth/secret/token)
+- `docs` (README/docs/*.md)
+- `release` (version/changelog)
+
+### appliesTo / exceptions Handling
+
+- If `appliesTo` exists, apply only when **scope/tags/path** matches
+- If `exceptions` matches, **exclude**
+
+### tokens Handling
+
+- If `tokens` exists, only target those appearing in diff
+- If not appearing, **skip to avoid noise**
+
+## Severity Mapping
+
+| priority | severity |
+|----------|----------|
+| p0 | Blocker |
+| p1 | Warning |
+| p2 | Suggestion |
+
+## Output Format (Markdown)
+
+```
+# Review: {target}
+
+## Summary
+- Blocker: N
+- Warning: N
+- Suggestion: N
+- Matched rules: X (of Y)
+- New rule proposals: Z
+
+## Findings
+
+### Blocker
+1. {short title}
+   - File: path/to/file.ts:123
+   - Evidence: {diff snippet}
+   - Rule: {rule.id} / {rule.text}
+   - Rationale: {rule.rationale}
+
+### Warning
+...
+
+### Suggestion
+...
+
+## Rule Coverage
+- Applied: {rule ids}
+- Skipped (scope mismatch): {rule ids}
+
+## Rule Proposals
+- {proposal} (source: {which finding triggered this})
+
+## Stale Rules
+- {rule.id} (lastSeenAt: YYYY-MM-DD)
+```
+
+## Review JSON Format
+
+Save to `.mneme/reviews/YYYY/MM/review-YYYY-MM-DD_HHMMSS.json`:
+
+```json
+{
+  "id": "review-2026-01-25_145500",
+  "createdAt": "2026-01-25T14:55:00Z",
+  "target": {
+    "type": "staged",  // or "pr" for GitHub PRs
+    "branch": "main"
+  },
+  "summary": {
+    "blocker": 1,
+    "warning": 2,
+    "suggestion": 3,
+    "matchedRules": 4,
+    "totalRules": 10,
+    "newRuleProposals": 1
+  },
+  "findings": [
+    {
+      "id": "finding-001",
+      "severity": "blocker",
+      "title": "Hardcoded production secret",
+      "ruleId": "review-2026-01-24_abc123-0",
+      "ruleText": "Secrets should be in environment variables",
+      "rationale": "Avoid leak risk",
+      "file": "src/config.ts",
+      "line": 42,
+      "evidence": "API_KEY = \"xxx\""
+    }
+  ],
+  "coverage": {
+    "appliedRuleIds": ["review-2026-01-24_abc123-0"],
+    "skippedRuleIds": ["dev-2026-01-20_def456-1"]
+  },
+  "proposals": [
+    {
+      "text": "API client must always set timeout",
+      "fromFindingIds": ["finding-002"]
+    }
+  ],
+  "staleRules": [
+    { "id": "dev-2025-12-01_aaa111-0", "lastSeenAt": "2025-12-05T00:00:00Z" }
+  ],
+  "context": {
+    "projectDir": "/path/to/project",
+    "branch": "main"
+  }
+}
+```
+
+### PR Review Target Format
+
+When reviewing a GitHub PR, use this target format:
+
+```json
+{
+  "target": {
+    "type": "pr",
+    "prSource": {
+      "owner": "owner",
+      "repo": "repo",
+      "prNumber": 123,
+      "url": "https://github.com/owner/repo/pull/123"
+    }
+  }
+}
+```
+
+### Updating Rule Effectiveness
+
+When rules are applied during review:
+1. Increment `appliedCount` for each matched rule
+2. After user feedback (accepted/rejected), update `acceptedCount`
+3. Update `lastAppliedAt` timestamp
+
+## Two-Stage Review JSON Format (--full)
+
+Extended format for `--full` reviews:
+
+```json
+{
+  "id": "review-2026-01-27_103000",
+  "createdAt": "2026-01-27T10:30:00Z",
+  "mode": "full",
+  "target": {
+    "type": "staged",
+    "branch": "feature/auth"
+  },
+
+  "specCompliance": {
+    "planFile": "docs/plans/2026-01-27-auth-tasks.md",
+    "designFile": "docs/plans/2026-01-27-auth-design.md",
+    "status": "pass",
+    "findings": [
+      {
+        "type": "missing",
+        "description": "Task 3: Add refresh token endpoint - not implemented",
+        "planReference": "### Task 3: Add refresh token endpoint"
+      },
+      {
+        "type": "mismatch",
+        "description": "JWT storage uses localStorage instead of httpOnly cookie",
+        "planReference": "## Security: Store tokens in httpOnly cookies",
+        "actualImplementation": "src/auth/storage.ts:15 - localStorage.setItem('token', ...)"
+      }
+    ]
+  },
+
+  "codeQuality": {
+    "summary": {
+      "blocker": 0,
+      "warning": 1,
+      "suggestion": 2
+    },
+    "findings": [
+      {
+        "id": "finding-001",
+        "severity": "warning",
+        "title": "Missing error handling",
+        "ruleId": "dev-error-handling-001",
+        "file": "src/auth/jwt.ts",
+        "line": 42
+      }
+    ]
+  },
+
+  "coverage": {
+    "appliedRuleIds": ["dev-error-handling-001"],
+    "skippedRuleIds": []
+  },
+  "proposals": [],
+  "staleRules": [],
+  "context": {
+    "projectDir": "/path/to/project",
+    "branch": "feature/auth"
+  }
+}
+```
+
+### specCompliance Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| planFile | string | Path to tasks.md used for verification |
+| designFile | string | Path to design.md used for verification |
+| status | `"pass"\|"fail"` | Whether spec compliance passed |
+| findings | array | List of compliance issues |
+
+### specCompliance Finding Types
+
+| Type | Description |
+|------|-------------|
+| `missing` | Planned item not implemented |
+| `mismatch` | Implementation differs from design |
+| `incomplete` | Partially implemented |
+
+## Recording Review in Session
+
+**Note:** Review interactions are auto-saved by SessionEnd hook.
+
+Review results are saved to `.mneme/reviews/` directory (separate from session files).
+
+If significant decisions were made during review (e.g., architectural changes), capture them via `/mneme:save`:
+
+```yaml
+discussions:
+  - topic: "Code review findings"
+    timestamp: "[ISO8601]"
+    decision: "[Key decision from review]"
+    reasoning: "[Why this change was required]"
+
+references:
+  - type: review
+    path: ".mneme/reviews/YYYY/MM/review-YYYY-MM-DD_HHMMSS.json"
+    description: "Review result"
+```