BotsIQ Change Verifier

BotsIQ Change Verifier is a privacy-first VS Code extension for developers using AI coding agents. It creates an evidence-based report of current Git workspace changes so you can review exact file-level impact before committing.

Current release: 1.0.6.

Marketplace extension ID: botsiq.botsiq-change-verifier.

To install the bundled VSIX package directly or for offline environments:

code --install-extension botsiq-change-verifier-1.0.6.vsix

Privacy & Security Architecture

This extension runs entirely inside VS Code against the currently opened Git workspace.

• No login is required.
• No backend connection is required.
• No web dashboard or workspace pairing is required.
• No source code, Git diff, report, file name, workspace path, or audit record is uploaded.
• Zero telemetry: no external tracking, telemetry, billing, or accounts required.
• Reports, request audits, snapshots, and logs are generated and stored locally under .botsiq/.

What It Reports

• Files created, updated, deleted, and renamed
• Staged and unstaged status for each file
• Risky paths based on configurable keywords such as auth, billing, security, env, config, and api
• Test file detection and a signal when production files changed without test changes
• Git diff stat and staged diff stat
• Branch, HEAD commit, timestamp, workspace name, recommendations, and audit-ready Markdown/JSON output
• Folder/module impact map
• CI-style command detection from package.json and common CI config files
• Configurable audit checklist from settings or .botsiq/policy.json
• Redacted secret scanning for credential-shaped strings in added diff lines
• Before/after snapshot comparison for tracking AI-agent change scope over time
• Tamper-evident SHA-256 audit hash for saved Markdown/JSON report pairs
• One-time native VS Code notification and compact editor popup after a completed agent task or idle AI-assisted file changes
• Automatic per-request JSON audit history with user request, in-scope files, out-of-scope files, and risk management changes
• Persisted verification sessions with pre-change baselines and chained change-event ledgers, including later-restored edits
• Worker-backed incremental JavaScript/TypeScript graph updates triggered by observed file changes, with SQLite graph indexing
• Compiler-backed symbols/imports/routes, schema-validated .botsiq/workflows.json and API checks, and coverage-aware verification planning

Commands

• BotsIQ: Generate Change Verification Report
• BotsIQ: Verify Completed Agent Task
• BotsIQ: Start Verification Session
• BotsIQ: Save Audit Report
• BotsIQ: Refresh Dashboard
• BotsIQ: Take Before Snapshot
• BotsIQ: Compare Against Before Snapshot
• BotsIQ: Run Detected Test Command
• BotsIQ: Export Report as HTML
• BotsIQ: Verify Report Integrity
• BotsIQ: Open Request Audit History
• BotsIQ: Configure GitHub Integration

The extension also adds a BotsIQ side panel in the Activity Bar with local dashboard metrics and action buttons. The dashboard opens directly, refreshes from current Git state, reads local request audit history when available, and highlights secret findings before an audit is saved.

If the selected workspace is not inside a Git repository, BotsIQ shows a local setup state instead of requiring any remote service.

Saved reports are written to .botsiq/reports/ by default. The save command writes Markdown and JSON. Markdown reports include a SHA-256 Audit Integrity block for the exact JSON file. HTML is available through the export command.

The JSON report format is documented in docs/api/report-schema.md for teams that want to review, parse, or archive audit evidence outside VS Code.

The repository .gitignore excludes .botsiq/ because local reports, request audits, snapshots, and logs can contain workspace paths, file names, review context, and redacted finding context. Do not commit these artifacts unless your team has explicitly reviewed their contents.

Automatic request audit records are written to .botsiq/requests/ by default. These JSON files are saved when BotsIQ detects completed AI-assisted changes or when BotsIQ: Verify Completed Agent Task is run. Use BotsIQ: Open Request Audit History to reopen any saved request audit.

Configuration

• botsiq.riskKeywords: array of path keywords to flag as risky
• botsiq.reportDirectory: workspace-relative directory for saved Markdown and JSON reports
• botsiq.requestAuditDirectory: workspace-relative directory for automatic per-request JSON audit records
• botsiq.auditChecklist: checklist items included in audit reports
• botsiq.popup.enabled: enable the one-time completion notification
• botsiq.popup.cooldownSeconds: fallback notification cooldown in seconds
• botsiq.popup.showOnRisk: show the notification when risk findings exist
• botsiq.popup.showWhenTestsMissing: show the notification when production changes have no matching test changes
• botsiq.popup.debounceSeconds: idle period after file writes before fallback verification runs
• botsiq.performance.maxFilesPerReport: maximum changed files included in the primary report view
• botsiq.performance.maxDiffLinesPerFile: maximum diff lines scanned per file
• botsiq.performance.diffTimeoutSeconds: maximum seconds to wait for Git diff collection before returning partial data
• botsiq.enableCloudFeatures: reserved for optional cloud features (disabled by default)
• botsiq.enableTelemetry: telemetry tracking (disabled by default)
• botsiq.github.enabled: enable optional GitHub integration for PR links and CI run enrichment
• botsiq.github.apiBaseUrl: custom GitHub API base URL (for GitHub Enterprise Server)

AI Coding Assistant Verification (Claude Code, Cursor, Codex, Copilot)

Use BotsIQ: Start Verification Session before Claude Code, Cursor, Codex, GitHub Copilot, or manual work begins. BotsIQ captures the request and pre-change baseline, then independently observes file events and reconciles the final Git state. Use BotsIQ: Verify Completed Agent Task when the task finishes to create the final audit record (BQ-YYYYMMDD-NNN).

The request is immutable after session start. If no request text is available, BotsIQ does not start a valid verification session; automatic fallback observations are explicitly marked UNKNOWN and INCOMPLETE rather than verified.

Team Policy

Teams can commit .botsiq/policy.json to standardize local audit behavior:

{
  "riskKeywords": ["auth", "billing", "security", "api"],
  "enforcementMode": "advisory",
  "auditChecklist": [
    { "text": "Reviewed risky paths", "required": true },
    { "text": "Ran tests", "required": false }
  ],
  "requiredCommands": ["npm test", "npm run build"],
  "auditMetadata": {
    "reviewerPrompt": true,
    "requireTicketId": false,
    "ciRunLinkTemplate": "https://github.com/{owner}/{repo}/actions/runs/{runId}"
  }
}

Policy values override matching VS Code settings where applicable. See docs/policy-reference.md for the full policy field reference.

Security And Integrity

Secret findings use the workspace policy enforcement mode:

• blocking: report display, save, and export are blocked until detected credentials are removed from the diff.
• warning: the operation continues, but BotsIQ shows a warning with the finding count.
• advisory: the operation continues and the report includes the secret findings section.

Use BotsIQ: Verify Report Integrity to select a saved Markdown report and compare its embedded hash against the paired JSON audit file. See docs/security.md.

Snapshots

Use BotsIQ: Take Before Snapshot before an AI-assisted change. BotsIQ saves a timestamped snapshot under .botsiq/snapshots/, while also keeping latest-before.json.

Use BotsIQ: Compare Against Before Snapshot to compare the current Git state against the latest before snapshot.

Dashboard Accessibility

The dashboard uses native buttons, labels, table captions, scoped headers, live regions, alert banners, focus indicators, reduced-motion CSS, and accessible risk severity color pairs. See docs/accessibility.md.

Continuous Integration

.github/workflows/ci.yml runs syntax checks, unit tests, and package validation across Linux, macOS, Windows, Node 18/20/22, and VS Code stable/insiders.

Marketplace Publishing

BotsIQ Change Verifier is packaged under the extension identifier botsiq.botsiq-change-verifier. The publisher field must match the registered Visual Studio Marketplace publisher ID before running vsce publish.

Before publishing a Marketplace update:

npm run test:all
npx @vscode/vsce ls
npx @vscode/vsce package
npx @vscode/vsce publish

If this is the first Marketplace release, confirm that the Marketplace publisher ID botsiq exists and that the publishing account has access to it before running npx @vscode/vsce publish.

If the extension does not appear immediately after publishing, search for the full extension ID first. Marketplace search indexing can lag behind the published item page.

Run Locally

1. Open this folder in VS Code.
2. Press F5 to start an Extension Development Host.
3. Open a Git repository in the Extension Development Host.
4. Run BotsIQ: Generate Change Verification Report from the Command Palette.
5. Run BotsIQ: Verify Completed Agent Task after a Claude Code or Codex task to show the one-time popup.
6. Run BotsIQ: Save Audit Report to write Markdown and JSON audit files.
7. Open the BotsIQ Activity Bar panel to use the dashboard buttons.
8. Run BotsIQ: Configure GitHub Integration to connect or verify GitHub integration.

Test

Run:

npm run check
npm test
npm run test:security
npm run validate:package
npm run ci

The test script creates a temporary Git repository, makes created, updated, deleted, renamed, and risky auth/login changes, then verifies classification, snapshots, saved reports, HTML export, secret scanning, and integrity checks.

Operational Considerations

• Rename detection follows Git status output and depends on Git recognizing the rename.
• The report summarizes file-level facts and diff stats, but does not inspect semantic code impact.
• The main report webview uses a simple preformatted Markdown preview.
• Multi-root aggregate reporting is not implemented.
• Dashboard checklist checks are local UI state only; saved reports store unchecked checklist items as audit prompts.
• All operations execute directly on your workstation without external server dependencies.