safety.md

Safety model, privacy and limits

Privacy model

• Private data lives in instances/<name>/ and in .cache/. Both are git-ignored and never published. Your repo is read, never written.
• Only the synthetic demo is public. Nothing from a real codebase belongs in this repo.
• A leak scan (npm run leak-scan) checks tracked files. A pre-push hook scans each commit, author and file version before it leaves your machine. The hook is a local aid, not a guarantee.
• No AI calls and no network. Building and answering run on your machine. The tool sends nothing anywhere.

Safety model

• Read-only. Your repo is read through git plumbing (ls-tree, cat-file, diff-tree, status) with locking, lazy fetch and fsmonitor off. Uncommitted edits are read only for admitted files, never through a symlink or junction. Otherwise the answer says UNKNOWN.
• Allowlist first. Files are admitted by path, type and size before anything is read. .env* files, key files, symlinks and submodules are always refused, whatever the config says.
• Redaction. Common email, phone, key and token patterns are redacted from the files meant for sharing: the index, cards, viewer and exports, file names included. It is pattern-based, so an unusual secret format could slip through. Fake "canary" secrets in the demo test this.
• What stays raw, on purpose. Terminal messages are redacted too. Three things are not, and must not be shared: the build cache in .cache/, which holds copies of your source for fast rebuilds; instances/<name>/brain.config.json, which holds your repo's path; and the text agent-snippet prints, which must carry this toolkit's exact path to work. The first two are git-ignored.
• Outputs stay here. Every write is checked to stay inside this folder and outside your repo. The one exception is agent-setup, which writes only the file you name, and only its own marked block (or, for Claude, a marked SKILL.md). It refuses to overwrite a file it did not write, and refuses any path that goes through a link or junction.
• Publishing your fork. npm run leak-scan checks tracked files. npm run leak-scan -- --dir <folder> checks an exact artifact, for example an unpacked npm pack tarball. Binary files are refused, with one narrow exception: PNG screenshots at docs/img/<name>.png, accepted only if the PNG signature and chunk structure are valid, with any text chunks scanned. The package ships only an allowlist of files (files in package.json). The pre-push hook (git config core.hooksPath .githooks) scans each commit, author and file version before it leaves your machine. It uses the private names found in your local instances, plus a .publish-denylist file that you create (git-ignored, one private word per line, at least one line). The hook refuses to push while that file is missing or empty. --no-verify or a disabled hook skips it.

Honest limits

• It saves no tokens. Measured: see measurement.md.
• Static reading is not runtime proof. It reads code; it does not run it. A table found in code is a path, not proof that saving works. A route guard in the browser is not server security. Each record keeps seven separate evidence fields: navigation, implementation, persistence, authorization, ui_presence, connected_readback and production_observation. The last three stay not examined until someone checks a real build.
• Unknown stays unknown. If a link can't be traced, the answer says so instead of guessing. That can mean missing implementation or a limit of the analyzer; the tool does not decide which.
• Derived, not authority. Design docs say what should happen, code shows what is built, and only runtime evidence shows what ran. The map records disagreements instead of resolving them.
• Parser coverage: React Router JSX routes and reducer-driven phone navigation, in TypeScript and JavaScript. Routes written as objects with createBrowserRouter are not detected. Other frameworks need a new adapter.
• A broken source file is reported, not refused. A file with syntax errors still builds, because a half-edited file is what the repo holds. The map names it as incompletely extracted, and freshness says FRESH_WITH_UNKNOWNS with the file names and count, never plain FRESH, until it is fixed and rebuilt.
• The viewer is a saved page. brain.html is a snapshot. It does not update itself. Opened on a map that has gone stale, it is a marked copy with a STALE banner. Exports of a stale map are refused unless you pass --allow-stale, and then carry a STATE.md with the warnings.
• Answers are not capped in size. Requirement lines are paged, but a long single field, such as a goal or a requirement's full text, is printed in full, never truncated.
• A broken design file never replaces a good map. A design file that is not valid JSON stops the build and the last valid map is kept; answers then say the design inputs changed.
• Freshness has edges. It covers the checkout you run from, your design files and the toolkit's code. It does not cover deployed or runtime state. An agent working in another worktree gets answers checked against that worktree, but only the configured checkout's map is rebuilt.
• Install by git clone. Installing from npm is not supported yet.
• Status: v0.1, a pilot. Expect rough edges.