Kjell Tore Guttormsen
2c9e2de00a
The burst counter incremented on any tool call <30s apart regardless of tool type, so a bulk read of many files produced the same "Rapid-fire" alert as a rapid-fire editing sequence. The edit-ratio check reported "possible stuck/spiral" for any session under 10% edits past 30 minutes, which a read-heavy analysis session satisfies structurally whether or not the work is productive. Both mechanisms are confirmed in docs/BRIEF-vurdering-v2.md, verification points 1a and 1b. tool-tracker.mjs now tracks whether the current burst run consists only of read tools and suppresses the rapid-fire alert for such runs. A read-dominant session (>=70% reads) reports its low edit ratio as context rather than as a stuck/spiral claim, and never as the sole reason for a warning. Bursts involving Edit/Write/Bash and non-read-dominant sessions behave exactly as before. No new data is recorded: the differentiation uses tool_name, which events.jsonl already logs. The privacy design is untouched. Tests first (Iron Law): 5 cases in tests/tool-tracker.test.mjs, 3 of which failed against the previous implementation, 2 of which are regression guards that passed before and still pass. Verified: node --test tests/*.test.mjs -> 263 pass, 5 fail. All 5 failures are the perf wall-clock assertions, which fail identically on HEAD without this change (measured by stashing and re-running) — they are a pre-existing property of this machine, not a regression. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011wMhJuPFUiWqKLSQjrzCXP
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# Interaction Awareness — Developer Reference
|
||
|
||
Claude Code plugin for AI interaction pattern awareness.
|
||
|
||
## Architecture
|
||
|
||
Four layers, each building on the previous:
|
||
|
||
- **Layer 1** (`skills/`) — SKILL.md behavioral overrides. Always active.
|
||
- **Layer 2** (`hooks/scripts/`) — Programmatic detection via 4 hook events.
|
||
Node.js (`.mjs`), cross-platform. Writes JSONL metadata to `${CLAUDE_PLUGIN_DATA}`.
|
||
- **Layer 3** (`commands/`) — User-triggered reports from Layer 2 data. Opt-in.
|
||
- **Layer 4** (`commands/interaction-report.md` Step 9) — Contemplative references. Opt-in.
|
||
|
||
## Key files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `hooks/scripts/lib.mjs` | Shared library: stdin, paths, thresholds, state, cooldowns, layer guards, DOMAIN_STAKES, readRecentEndRecords |
|
||
| `hooks/scripts/session-start.mjs` | SessionStart: register session, count daily, night check |
|
||
| `hooks/scripts/prompt-analyzer.mjs` | UserPromptSubmit: pattern flags (NEVER logs prompt text) |
|
||
| `hooks/scripts/tool-tracker.mjs` | PostToolUse: events, edit ratio, burst, alerts |
|
||
| `hooks/scripts/session-end.mjs` | SessionEnd: finalize JSONL, cleanup state |
|
||
| `hooks/hooks.json` | Hook event registration (4 events) |
|
||
| `skills/ai-psychosis/SKILL.md` | Layer 1 behavioral instructions |
|
||
| `commands/interaction-report.md` | Layer 3 slash command: `/interaction-report [weekly\|monthly\|all]` |
|
||
| `hooks/scripts/report-reader.mjs` | Layer 3 helper: reads sessions.jsonl with v1.0.0 backward compat |
|
||
|
||
Legacy bash scripts were removed in v1.0 (available in git history).
|
||
|
||
## Data storage
|
||
|
||
```
|
||
$CLAUDE_PLUGIN_DATA/
|
||
├── sessions.jsonl Compact JSONL, one record per session
|
||
├── events.jsonl {ts, session_id, tool_name} per tool call
|
||
└── state/
|
||
└── <session_id>.json Live state during active session
|
||
```
|
||
|
||
State files are created at SessionStart and deleted at SessionEnd.
|
||
|
||
## Hard constraints
|
||
|
||
- **Cross-platform** — Node.js only, no bash/jq dependency
|
||
- **Privacy** — prompt text NEVER written to disk. Boolean flags only.
|
||
- **Performance** — hooks must complete in <100ms
|
||
- **Non-blocking** — never exit 2, never require confirmation
|
||
- **No network** — everything local
|
||
- **Zero npm dependencies** — Node.js stdlib only (fs, path, os)
|
||
|
||
## Layer configuration
|
||
|
||
Global config at `~/.claude/ai-psychosis.local.md`, or per-project override at `<project>/.claude/ai-psychosis.local.md`:
|
||
|
||
```yaml
|
||
---
|
||
layer2: true # default on
|
||
layer3: false # default off
|
||
layer4: false # default off
|
||
---
|
||
```
|
||
|
||
`requireLayer(N)` in lib.mjs exits with `{"continue": true}` if layer N is disabled.
|
||
|
||
## Testing
|
||
|
||
Automated test suite using `node:test` (263 cases, zero npm dependencies):
|
||
|
||
```bash
|
||
node --test tests/*.test.mjs
|
||
```
|
||
|
||
| File | Cases | Coverage |
|
||
|------|-------|----------|
|
||
| `tests/session-start.test.mjs` | 11 | State init, JSONL, tier-2 cross-session alert |
|
||
| `tests/prompt-analyzer.test.mjs` | 100 | All v1.x patterns × 2 + thresholds + valence + v1.2 pushback contract |
|
||
| `tests/tool-tracker.test.mjs` | 13 | Counting, burst, reminders + read-tool calibration |
|
||
| `tests/session-end.test.mjs` | 7 | Finalize, duration, flags, v1.1.0 string + v1.2 array shapes |
|
||
| `tests/privacy.test.mjs` | 7 | Canary + matched-phrase × original + 5 v1.2 detector variants |
|
||
| `tests/skill-md.test.mjs` | 3 | Constitution citation + Score 5 + 11 guidance criteria |
|
||
| `tests/perf.test.mjs` | 9 | 4 hooks × 2 modes + 1000-record sessions.jsonl wall-clock |
|
||
| `tests/interaction-report.test.mjs` | 6 | report-reader.mjs v1.0/v1.1/v1.2 + SC-12 stdout assertions |
|
||
| `tests/lib.test.mjs` | 17 | Threshold constants + DOMAIN_STAKES + readRecentEndRecords |
|
||
| `tests/domain-detection.test.mjs` | 39 | 8 new domains × positive + adjacent-domain negatives + multi-domain |
|
||
| `tests/user-info.test.mjs` | 24 | yes_people/yes_digital/no priority + sticky + tier-1 alert |
|
||
| `tests/validation-seeking.test.mjs` | 20 | valseek detection + accumulation + domain-gated alert |
|
||
| `tests/stakes-matrix.test.mjs` | 7 | Stakes weighting on v1.2 alerts; v1.1.0 sensitivity preserved |
|
||
|
||
## Conventions
|
||
|
||
- Conventional Commits: `type(scope): description`
|
||
- English for all code, comments, and documentation
|
||
- Norwegian for project-internal communication
|