BotsIQ Change Verifier

BotsIQ Change Verifier is a local-only 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.1.

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

Marketplace publishing may not be visible until the first vsce publish completes and search indexing catches up. Until then, install the bundled VSIX locally:

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

Local-Only MVP

This MVP 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.
• No cloud telemetry, billing, subscription, or account feature is included in the current MVP.
• Reports, request audits, snapshots, and logs are generated and stored locally under .botsiq/.

The preserved web/ and supabase/ folders are future-development code only. They are not required for the extension to run and are excluded from the VSIX package.

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

Commands

• BotsIQ: Generate Change Verification Report
• BotsIQ: Verify Completed Agent Task
• 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

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 future cloud functionality; disabled in the current MVP
• botsiq.enableTelemetry: telemetry is disabled in the current MVP

Claude Code and Codex Completion

Use BotsIQ: Verify Completed Agent Task when Claude Code, Codex, or another coding agent has finished its task. BotsIQ also watches for quiet Git workspace changes and can show a native VS Code notification plus a compact editor popup with the user request, changed files under scope, changed files out of scope, and risk management changes.

The user request comes from the active completion context when available, or from BOTSIQ_USER_REQUEST / AIGUARD_USER_REQUEST. If no request text is available, BotsIQ still saves the JSON audit and marks the file scope review as needing request context.

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.

Test

Run:

npm run check
npm test
npm run validate:package
npm run test:all

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.

MVP Limitations

• 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.
• Web dashboard, pairing, cloud telemetry, billing, and account management are reserved for a future version and are disabled in this local-only MVP.