Skip to content

docs: add CLAUDE.md with wiki references #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ziomancer wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: add CLAUDE.md with wiki references #12

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Is

Drawbridge is a session-aware content sanitization pipeline for AI agents. It wraps ClawMoat (prompt injection + PII scanner) with syntactic pre-filtering, exponential-decay frequency tracking, escalation tiers, content redaction, context-aware profiles, audit trails, and alerting. Published on npm as `@vigil-harbor/clawmoat-drawbridge` (v1.2.0). An OpenClaw plugin is available at `extensions/drawbridge/`.

## Build & Run

```bash
npm install
npm run build # tsc → dist/
npm test # vitest run
npm run test:watch # vitest (watch mode)
npm run typecheck # tsc --noEmit
```

### OpenClaw plugin (extensions/drawbridge/)

```bash
cd extensions/drawbridge
npm install
npm run build
npm test
```

## Architecture

### Two packages in one repo

- **Root (`src/`)** — standalone npm library (`@vigil-harbor/clawmoat-drawbridge`). Core pipeline, scanner, frequency tracker, profiles, audit, alerting, sanitization.
- **Plugin (`extensions/drawbridge/`)** — OpenClaw plugin (`@vigil-harbor/openclaw-drawbridge`). Hook-only integration: message_received, before_dispatch, message_sending, llm_output, tool_result_persist, gateway_stop.

### Pipeline flow (DrawbridgePipeline.inspect)

```
Trust check → Syntactic pre-filter (17 rules, NFKC normalized)
→ Frequency update → Two-pass gate → Schema validation (MCP)
→ Scanner (ClawMoat) → Frequency update → Sanitize (redact)
→ Audit events → Alert evaluation → PipelineResult
```
Comment on lines +37 to +42
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add a language identifier to the fenced pipeline block.

This block triggers MD040 and will keep markdownlint noisy until fixed.

Suggested patch 
-```
+```text
 Trust check → Syntactic pre-filter (17 rules, NFKC normalized)
 → Frequency update → Two-pass gate → Schema validation (MCP)
 → Scanner (ClawMoat) → Frequency update → Sanitize (redact)
 → Audit events → Alert evaluation → PipelineResult
</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 37-37: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 37 - 42, The fenced pipeline block uses triple
backticks without a language tag which triggers markdownlint rule MD040; update
the fenced code block around the pipeline diagram (the triple-backtick block
containing "Trust check → Syntactic pre-filter..." lines) to include a language
identifier such as text (e.g., replace ``` with ```text) so the block is
explicitly annotated and MD040 is resolved.


### Key modules

- `src/pipeline/index.ts` (~600 lines) — full orchestration
- `src/validation/index.ts` (~490 lines) — PreFilter + SchemaValidator
- `src/alerting/index.ts` (~450 lines) — AlertManager
- `src/frequency/index.ts` (~400 lines) — FrequencyTracker
- `extensions/drawbridge/src/hooks/tool-error-enricher.ts` (~350 lines) — MCP tool error recovery

### Frequency & escalation

Per-session exponential decay scoring (half-life 60s) + rolling window counters:
- Tier 1 (>10): forced deep inspection
- Tier 2 (>20): enhanced scrutiny
- Tier 3 (>35): session termination (cannot be disabled)

### Profiles

5 built-in: general, customer-service, code-generation, research, admin. Custom profiles supported via ProfileResolver.

## Key Conventions

- **TypeScript ESM** — `"type": "module"`, `moduleResolution: "NodeNext"`, `.js` extensions in imports
- **ClawMoat is an optional peer dep** — fail-open if missing; syntactic pre-filter still runs
- **Pipeline never throws** — all errors caught and returned in PipelineResult
- **Frozen exports** — built-in profiles, syntactic rules, and default configs are deepFrozen
- **602+ tests** — core library (424) + plugin (178). Run both before publishing.
- **HMAC-SHA256 for redaction hashing** — opt-in via `hashRedactions: true`

## Wiki

The Vigil Harbor wiki lives at `C:\Users\zioni\Documents\Vigil-Harbor\vigil-harbor-wiki`.
Read `SCHEMA.md` for conventions and maintenance rules.
Comment on lines +74 to +75
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Avoid a machine-specific wiki path in shared docs.

C:\Users\... only works on one workstation; this makes the guidance non-portable for other contributors and CI/devcontainer setups. Prefer a repo-relative convention or a configurable env var.

Suggested patch 
-The Vigil Harbor wiki lives at `C:\Users\zioni\Documents\Vigil-Harbor\vigil-harbor-wiki`.
+The Vigil Harbor wiki lives in your local clone of `vigil-harbor-wiki` (set `VIGIL_HARBOR_WIKI_PATH` to its absolute path).
+Example:
+`$VIGIL_HARBOR_WIKI_PATH`
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 74 - 75, Replace the machine-specific absolute path
"C:\Users\zioni\Documents\Vigil-Harbor\vigil-harbor-wiki" in CLAUDE.md with a
portable repo-relative or configurable reference (e.g., "./vigil-harbor-wiki" or
use an env var placeholder like "$WIKI_PATH") and update the sentence to
instruct contributors to clone or symlink the wiki into that repo-relative
location or set the env var; ensure the README line and any examples reference
the chosen convention consistently so CI/devcontainer and other contributors can
follow it.


Before starting implementation:
1. Read `index.md` to orient.
2. Read `projects/drawbridge/architecture.md` and `projects/drawbridge/state.md`.
3. Read `projects/drawbridge/filemap.md` before modifying files.

After completing work:
1. Update filemap and state for Drawbridge.
2. Create a `decisions/` entry for any non-obvious judgment calls.
3. Append to `log.md`.
Loading