@f4bioo/berry-shield 2026.3.3-1

package/docs/wiki/decision/README.md

@@ -0,0 +1,48 @@
+---
+summary: "Decision reference index for Berry Shield mode logic, matching behavior, and security posture"
+read_when:
+  - Reviewing how Berry Shield decides allow/block/redact outcomes
+  - Updating mode and policy behavior documentation
+title: "Decision Reference"
+---
+
+# `Decision reference`
+
+This page is the entry point for Berry Shield decision logic documentation.
+If decision behavior changes, update this index and linked pages.
+
+## Security posture snapshot
+
+Berry Shield decision logic is strong at application-layer mitigation, but it is not host isolation.
+
+Known constraints to keep in mind:
+- Some protections depend on OpenClaw hook availability/invocation on the deployed runtime version.
+- Context injection paths influence model behavior, but are not hard execution control.
+- Persistence-time hooks can have timing gaps relative to in-turn model exposure.
+
+See full posture and limits:
+- [security posture](posture.md)
+
+## Decision pages
+
+- [modes](modes.md) (audit/enforce behavior and relation to policy profile)
+- [patterns](patterns.md) (pattern categories and matching pipeline)
+- [security posture](posture.md) (scope boundaries and SDK constraints)
+
+## Decision flow (high-level)
+
+1. Incoming operation is intercepted by a layer.
+2. Relevant data is extracted for matching.
+3. Pattern/rule matching evaluates risk.
+4. Runtime mode and policy context determine outcome.
+5. Layer returns allow, block, redact, or audit event path.
+
+## Notes
+- Decision docs must be aligned with runtime behavior, not intended behavior.
+- Claims about security behavior must be scoped and evidence-based.
+
+---
+
+## Navigation
+- [Back to Wiki Index](../README.md)
+- [Back to Repository README](../../../README.md)

package/docs/wiki/decision/modes.md

@@ -0,0 +1,176 @@
+---
+summary: "Decision model for audit and enforce runtime behavior, and how mode interacts with profile/adaptive policy"
+read_when:
+  - You need to reason about allow/block/redact outcomes
+  - You are validating audit vs enforce behavior in real runs
+  - You are debugging mismatches between expected and observed security outcomes
+title: "modes"
+---
+
+# `modes`
+
+This page defines how Berry Shield runtime mode affects security decisions.
+
+## What this page defines
+
+- What `audit` means in decision paths.
+- What `enforce` means in decision paths.
+- How mode differs from profile.
+- How adaptive triggers interact with mode.
+- Which outcomes to expect in common scenarios.
+
+## Mental model
+
+Mode answers this question:
+
+**After risk is detected, should the system only record intent, or actively mitigate?**
+
+- `audit` is observation-first posture.
+- `enforce` is mitigation-first posture.
+
+Mode does not define how frequently policy text is injected into agent context.  
+That belongs to profile/adaptive policy behavior.
+
+## Decision order (runtime perspective)
+
+1. A layer intercepts an operation or message.
+2. The layer extracts match candidates (path, command, output text, etc.).
+3. Rule matching determines whether risk is present.
+4. Mode determines whether matched risk is recorded-only or actively mitigated.
+5. The layer emits decision outcomes (for example would_block, blocked, would_redact, redacted) according to mode and path.
+
+## Mode behavior
+
+### audit
+
+In audit mode, risk matches are treated as observable events.
+
+Expected behavior pattern:
+- decision events are still produced and logged
+- operation flow generally continues
+- outputs generally remain unblocked by mode-level mitigation
+
+Important clarification:
+- audit is **shadow mode for block/redact mitigation paths**
+- audit is **not** "plugin fully passive"
+- policy-injection strategy (full/short/none) still follows profile/adaptive settings
+- message hygiene guards can still run (for example stripping leaked `<berry_shield_policy>` snippets)
+
+Audit mode is useful for:
+- measuring policy impact before hard enforcement
+- understanding false-positive surface
+- collecting decision evidence for rule tuning
+
+### enforce
+
+In enforce mode, risk matches are treated as active mitigation points.
+
+Expected behavior pattern:
+- risky operations may be denied before execution
+- risky output may be redacted before delivery
+- decision events reflect active mitigation outcomes
+
+Enforce mode is useful for:
+- production workloads
+- safety-critical environments
+- workflows where prevention is required, not only observation
+
+## Mode vs profile
+
+Mode and profile solve different problems:
+
+- Mode (`audit | enforce`) controls **mitigation posture** after risk is detected.
+- Profile (`strict | balanced | minimal`) controls **policy-injection strategy** in agent context.
+
+These controls are complementary:
+- Changing profile does not change mode identity.
+- Changing mode does not change profile strategy.
+
+## Adaptive trigger interaction
+
+Adaptive triggers (for example denied-based escalation windows and stale-based reinjection windows) change policy-injection intensity over time.
+
+They do not redefine runtime mode.
+
+Practical implication:
+- You can have `enforce + minimal` (active mitigation with quieter injection strategy).
+- You can have `audit + strict` (strong policy-injection strategy with observation-first mitigation posture).
+
+## Layer mapping (mode behavior by layer)
+
+### Stem (security gate tool)
+- audit: emits would_block events and allows flow to continue.
+- enforce: emits blocked events and returns denied outcomes.
+
+### Thorn (before_tool_call hook)
+- audit: emits would_block events and does not hard-block the call.
+- enforce: emits blocked events and returns block response.
+
+### Vine (external-content trust guard)
+- audit: records trust-risk outcomes as would_block without hard-block.
+- enforce: can block sensitive actions when external-risk state is active.
+
+### Pulp (output scanner hooks)
+- audit: emits would_redact events and preserves content for observation paths.
+- enforce: emits redacted events and returns redacted content.
+
+### Message policy-block hygiene
+- outgoing message sanitation may still strip leaked `<berry_shield_policy>` snippets as a hygiene guard.
+- this is not equivalent to full secret redaction behavior.
+
+## Scenarios
+
+### Scenario A: mode=enforce, profile=balanced
+
+- operation hits a risky match
+- runtime can actively deny/redact
+- policy injection follows balanced adaptive strategy
+
+Use case: default recommended operational baseline.
+
+### Scenario B: mode=audit, profile=strict
+
+- operation hits a risky match
+- runtime records decision outcomes as audit evidence
+- policy injection remains strong/explicit by profile strategy
+
+Use case: pre-enforcement tuning with high policy visibility.
+
+### Scenario C: mode=enforce, profile=minimal
+
+- operation hits a risky match
+- runtime can still deny/redact
+- policy injection stays low-noise unless adaptive triggers escalate
+
+Use case: low-noise interaction with active safety barriers.
+
+## Limits and non-goals
+
+- Mode behavior is constrained by available runtime hooks.
+- Hook availability/timing can affect when mitigation is observable.
+- Mode does not provide host-level sandboxing or kernel isolation.
+- Mode should not be interpreted as complete exploit prevention.
+
+## See CLI
+
+For operational command usage:
+- [CLI mode command](../operation/cli/mode.md)
+- [CLI status command](../operation/cli/status.md)
+- [CLI profile command](../operation/cli/profile.md)
+- [CLI policy command](../operation/cli/policy.md)
+- [CLI vine command](../operation/cli/vine.md)
+
+## Related pages
+- [decision index](README.md)
+- [patterns](patterns.md)
+- [security posture](posture.md)
+- [stem layer](../layers/stem.md)
+- [thorn layer](../layers/thorn.md)
+- [vine layer](../layers/vine.md)
+- [pulp layer](../layers/pulp.md)
+
+---
+
+## Navigation
+- [Back to Decision Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/decision/patterns.md

@@ -0,0 +1,137 @@
+---
+summary: "Decision reference for pattern categories and matching pipeline used by Berry Shield"
+read_when:
+  - Reviewing how Berry Shield matches risk patterns
+  - Updating rule categories or matching behavior docs
+title: "patterns"
+---
+
+# `patterns`
+
+Berry Shield decisions are driven by pattern matching.  
+This page explains the decision contract: what is matched, where rules come from, and how matches become runtime outcomes.
+
+## What this page defines
+
+- Pattern families used by runtime decisions.
+- Built-in versus custom rule sources.
+- The matching pipeline from candidate extraction to allow/block/redact outcomes.
+- Known limits so operators can tune with realistic expectations.
+
+## Pattern categories
+
+### Secret patterns
+Detect credential-like material in text payloads (API keys, tokens, private keys, secrets).
+
+Primary effect:
+- feeds redaction-related paths (for example output scanning and input auditing)
+- contributes to observation or sanitization outcomes depending on mode
+
+### PII patterns
+Detect personally identifiable information markers in text payloads.
+
+Primary effect:
+- feeds redaction-related paths
+- contributes to privacy-preserving output behavior and audit signals
+
+### Sensitive file patterns
+Detect sensitive file paths or file references in operation targets.
+
+Primary effect:
+- feeds operation-gating paths
+- contributes to observation or deny outcomes depending on mode
+
+### Destructive command patterns
+Detect destructive command intent before execution (for example unsafe deletion/format/destructive shell patterns).
+
+Primary effect:
+- feeds pre-execution safety gates
+- contributes to observation or deny outcomes depending on mode
+
+## Rule sources
+
+### Built-in rules
+Bundled with Berry Shield and loaded by default.
+
+Operational meaning:
+- baseline security coverage exists without custom configuration
+- built-in coverage should be treated as starter baseline, not complete environment-specific policy
+
+### Custom rules
+User-defined patterns persisted via CLI operations.
+
+Operational meaning:
+- used to close environment-specific gaps
+- merged into runtime matching pipeline with built-in rules
+
+## Matching pipeline (runtime view)
+
+1. Layer intercepts a candidate event (tool call, tool result, outgoing message, input message).
+2. Layer extracts matchable candidate data (command text, path, content payload).
+3. Category-specific patterns are evaluated against candidate data.
+4. Match result is passed into layer decision logic.
+5. Mode (`audit` vs `enforce`) maps match result to observation-only or active mitigation outcome.
+6. Runtime emits structured event outcome for reporting.
+
+## Built-in + custom merge behavior
+
+At runtime, Berry composes effective pattern sets by category:
+- redaction patterns: built-in secret + built-in PII + custom secret-like additions
+- file patterns: built-in sensitive-file + custom sensitive-file additions
+- command patterns: built-in destructive-command + custom destructive-command additions
+
+The runtime uses cached compiled sets for synchronous checks.  
+Rule reload refreshes cache from persisted custom rules.
+
+## How patterns map to layers
+
+- Operation-gating patterns (sensitive files, destructive commands) are consumed by operation layers.
+- Redaction patterns (secrets, PII) are consumed by content-scanning layers.
+- External-origin trust signals are consumed by Vine for prompt-injection hardening.
+
+See layer details:
+- [See layer Stem](../layers/stem.md)
+- [See layer Thorn](../layers/thorn.md)
+- [See layer Vine](../layers/vine.md)
+- [See layer Pulp](../layers/pulp.md)
+- [See layer Leaf](../layers/leaf.md)
+
+## Practical outcomes by mode
+
+When a match is found:
+- in `audit`, runtime usually records intent without heavy mitigation
+- in `enforce`, runtime may actively deny operations or sanitize content and emit mitigation outcomes
+
+Mode semantics are defined in:
+- [modes](modes.md)
+
+## Tuning guidance
+
+Use built-in rules as default baseline, then tune in this order:
+1. Measure with `audit` to observe match volume and false-positive surface.
+2. Add targeted custom rules for environment-specific secrets/paths/commands.
+3. Validate expected outcomes in `enforce` before production rollout.
+
+## Limits and non-goals
+
+- Pattern matching is heuristic, not complete semantic understanding.
+- Coverage can vary by platform path conventions and tool argument formats.
+- Some bypass forms depend on how candidate text is extracted by each layer.
+- Pattern matching does not replace host sandboxing, IAM hardening, or network controls.
+
+## See CLI
+
+For pattern lifecycle operations, see:
+- [CLI add command](../operation/cli/add.md)
+- [CLI list command](../operation/cli/list.md)
+- [CLI test command](../operation/cli/test.md)
+
+## Related pages
+- [decision index](README.md)
+- [modes](modes.md)
+
+---
+
+## Navigation
+- [Back to Decision Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/decision/posture.md

@@ -0,0 +1,68 @@
+---
+summary: "Security posture reference for Berry Shield scope boundaries and SDK dependency constraints"
+read_when:
+  - Reviewing what Berry Shield does and does not protect
+  - Assessing SDK/runtime constraints that affect enforcement confidence
+title: "security posture"
+---
+
+# `security posture`
+
+Berry Shield is a session-level security layer inside OpenClaw plugin boundaries.
+
+## Scope boundaries
+
+### In scope
+- prompt and tool-level policy guidance for agent behavior
+- pre-execution checks for risky operations
+- output redaction and audit event generation
+
+### Out of scope
+- kernel-level sandboxing
+- host-level container isolation
+- operating-system exploit mitigation
+
+Berry Shield must be understood as application-layer protection, not host isolation.
+
+## Dependency on OpenClaw hooks
+
+Berry Shield behavior depends on hook surfaces provided by OpenClaw runtime.
+Changes in hook timing, propagation, or runner behavior can change effective security posture.
+
+## Known host constraints (OpenClaw-side)
+
+- Hook definition is not the same as effective runtime invocation.
+  Verify behavior on the deployed OpenClaw build/version, not only by reading hook types.
+- `before_agent_start` is instruction-level influence on context, not hard runtime execution control.
+- `tool_result_persist` runs at persistence time; this can create timing gaps relative to what the model already saw in the same turn.
+- Hook execution semantics (sync-only paths, void vs modifying hooks) are host constraints and can weaken assurance if misunderstood.
+
+## Practical posture guidance
+
+### Preferred baseline
+- mode set to enforce for active mitigation behavior
+- policy/profile configured intentionally for the deployment context
+- status and report reviewed during validation cycles
+
+## See CLI
+
+For posture verification operations, see:
+- [CLI status command](../operation/cli/status.md)
+- [CLI report command](../operation/cli/report.md)
+
+## Known risk classes
+
+- prompt-level override attempts against weak policy instruction context
+- bypass attempts through alternate tool paths when coverage is incomplete
+- operational drift when mode/policy differs from expected deployment baseline
+- runtime-version drift where expected hook behavior differs from deployed host behavior
+
+## Related pages
+- [decision index](README.md)
+- [modes](modes.md)
+
+---
+
+## Navigation
+- [Back to Decision Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/deploy/README.md

@@ -0,0 +1,51 @@
+---
+summary: "Deployment index for installation tracks, local build flow, and GitHub CI/CD release flow"
+read_when:
+  - You need to install Berry Shield in a real environment
+  - You need to choose between source-truth and release-truth deployment
+  - You need pre-release validation and audit gates
+  - You need the official GitHub release workflow (prepare-release/publish)
+title: "Deploy Reference"
+---
+
+# `Deploy reference`
+
+This domain explains how to deploy Berry Shield safely and repeatably.
+It covers installation tracks, local build gates, GitHub release workflow, and validation flow.
+
+## Deployment tracks
+
+Berry supports two operational tracks:
+
+- Source-truth track: run exactly what is in this repository (build from source).
+- Release-truth track: consume published package artifact from the package registry.
+
+Choose source-truth when you need repository-level auditability; choose release-truth when you need immutable package consumption.
+
+## Pages
+
+- [installation](installation.md): installation paths and post-install verification
+- [build](build.md): local development build and preflight gates
+- [github-ci-cd](github-ci-cd.md): official GitHub Actions release workflow (`normal` and `reconcile`)
+- [auditing](auditing.md): wiki sanity and documentation quality gates
+
+## Recommended sequence (local -> CI/CD)
+
+1. Choose installation track (source-truth or release-truth).
+2. Validate local quality gates using [build](build.md).
+3. Create release branch and PR via [github-ci-cd](github-ci-cd.md) (`prepare-release`).
+4. Merge release PR into `master`.
+5. Run publish workflow in [github-ci-cd](github-ci-cd.md) (`normal` or `reconcile`).
+6. Verify runtime mode/status/report.
+
+## Related pages
+- [wiki index](../README.md)
+- [operation index](../operation/README.md)
+- [CLI init](../operation/cli/init.md)
+- [CLI status](../operation/cli/status.md)
+
+---
+
+## Navigation
+- [Back to Wiki Index](../README.md)
+- [Back to Repository README](../../../README.md)

package/docs/wiki/deploy/auditing.md

@@ -0,0 +1,56 @@
+---
+summary: "Documentation sanity gate reference for deploy and release workflows"
+read_when:
+  - You are validating wiki quality before release
+  - You need to understand warning vs error behavior in doc sanity
+  - You are enforcing documentation consistency gates
+title: "auditing"
+---
+
+# `Auditing and sanity`
+
+Berry wiki quality is validated by the doc sanity script.
+This gate is part of release validation flow and should be run before shipping documentation changes.
+
+## Main command
+
+```bash
+npm run wiki:claim
+```
+Result: Runs documentation sanity checks and reports warnings/errors.
+
+## What the sanity gate checks
+
+- Symbol/reference integrity against code exports.
+- Link validity and case-sensitive path correctness.
+- Claim/evidence consistency checks.
+- Tone and density warnings for documentation quality.
+- CLI contract checks for command-block formatting in markdown.
+
+## Warning vs error behavior
+
+- Warnings report quality issues but do not fail process exit by default.
+- Errors trigger non-zero exit and fail the gate.
+
+Operational implication:
+- Release pipelines should treat errors as blocking.
+- Teams may choose stricter policy for warnings at final review stage.
+
+## Recommended workflow
+
+1. Edit docs in focused scope.
+2. Run sanity gate.
+3. Fix blocking errors first.
+4. Resolve tone and consistency warnings according to team policy.
+
+## Related pages
+- [deploy index](README.md)
+- [build](build.md)
+- [installation](installation.md)
+
+---
+
+## Navigation
+- [Back to Deploy Index](README.md)
+- [Back to Wiki Index](../README.md)
+

package/docs/wiki/deploy/build.md

@@ -0,0 +1,92 @@
+---
+summary: "Local build and validation reference for Berry Shield development workflow"
+read_when:
+  - You are preparing a local development artifact
+  - You need to run local quality gates before opening a PR
+  - You are validating package scripts on your workstation
+title: "build"
+---
+
+# `Build (Local Dev)`
+
+Berry local build flow is script-driven from package.json.
+This page documents workstation commands only (not GitHub release workflows).
+
+## Core build commands
+
+### Build artifact
+
+```bash
+npm run build
+```
+Expected: `dist/index.js` is generated from `src/index.ts`.
+
+### Type checking
+
+```bash
+npm run typecheck
+```
+Result: TypeScript graph is validated without emitting files.
+
+### Test suite
+
+```bash
+npm run test
+```
+Result: Vitest suite executes and reports pass/fail status.
+
+## Local pre-release gates
+
+### Preflight gate
+
+```bash
+npm run release:preflight
+```
+Result: Runs build, typecheck, `vitest` on `__tests__`, and wiki sanity gate.
+
+## What local preflight validates
+
+- Build success.
+- Type safety.
+- Test suite status.
+- Wiki sanity gate status (`npm run wiki:claim`).
+
+## Practical use guidance
+
+- For normal development deploy checks, run build + typecheck + test.
+- For release candidate verification, run release:preflight.
+- For GitHub release workflows (`prepare-release` / `publish`), see `github-ci-cd.md`.
+
+## Common failure: compatibility policy test
+
+Symptom:
+- `__tests__/compat-policy.test.ts` fails after local SDK updates.
+
+Why:
+- local `node_modules/openclaw` version does not satisfy `package.json` peer range, or
+- peer range is not aligned with `COMPAT_POLICY` constants.
+
+How to fix:
+1. Check local SDK version:
+```bash
+npm ls openclaw
+```
+Expected: installed version satisfies `peerDependencies.openclaw`.
+
+2. Reinstall dependencies if local graph is stale:
+```bash
+npm install
+```
+Expected: dependency graph is refreshed and tests can validate policy contract.
+
+## Related pages
+- [deploy index](README.md)
+- [installation](installation.md)
+- [auditing](auditing.md)
+- [GitHub CI/CD release flow](github-ci-cd.md)
+
+---
+
+## Navigation
+- [Back to Deploy Index](README.md)
+- [Back to Wiki Index](../README.md)