CodeRoot.ai — Human vs AI vs Untracked, Made Clear

CodeRoot.ai gives your team clear, objective visibility into how code gets made. It centers on a simple lens — Human vs AI vs Untracked — and turns everyday editing into consistent, trustworthy reports. With that shared view, teams can discuss AI usage with facts instead of anecdotes and make better decisions about quality, ownership, and velocity.

PLACEHOLDER: HERO SCREENSHOT — Report overview (workspace composition)

Why it matters

What CodeRoot.ai is

CodeRoot.ai provides a shared lens on creation:

Reports are deterministic: the same inputs produce the same outputs, so comparisons remain stable over time.

Scope Guard: Similarity / winnowing / fingerprint-based analyses are intentionally excluded from the 0.4.x hardening effort. Any references or flags proposing them should be treated as out-of-scope until a post-hardening plan is approved.

Determinism Addendum (H-005)

Determinism underpins trust in comparisons across machines and CI runs. CodeRoot normalizes report output before hashing so non-semantic volatility (ordering, runtime durations) never changes the determinism hash.

Normalization pipeline:

1. Generate full payload (JSON + Markdown) with kpis, chart_data, notes, diagnostics.
2. Deep-clone payload; remove volatile / presentation fields: diagnostics, notes, chart_data.
3. Recursively sort object keys lexicographically.
4. Serialize the normalized object and compute a SHA-256 digest.
5. Embed { determinism: { normalized_hash } } into the final JSON artifact.

Excluded fields rationale:

Repro recipe:

# Run twice; hashes must match
node bin/coderoot-report-strict.mjs .
grep normalized_hash .coderoot/v1/reports/coderoot-report.json
node bin/coderoot-report-strict.mjs .
grep normalized_hash .coderoot/v1/reports/coderoot-report.json

Ordering guarantees:

• File list, developer map (materialized arrays), and date keys are inserted after explicit sorting.
• Any map-like object added in the future MUST be sorted before emission to preserve hash stability.

If a structural (schema) change is required, bump the report schema version (e.g. coderoot.report/0.5) and retain the prior hash process unchanged for backward compatibility.

Audit mode interplay: enabling attribution audit adds nested episode rationale under file entries; these objects are fully included in normalization (excluding only the global volatile fields), so audit mode yields a different, but still stable, hash.

How it works (high level)

You work as usual in VS Code. CodeRoot.ai observes local editing signals and maintains a small, local .coderoot/ folder in your repository. From that, it generates a report centered on Human vs AI vs Untracked, with optional deep dives by developer, by file, and by day. No servers are contacted; all analysis runs locally.

graph TD
  A[Write Code in VS Code] --> B[CodeRoot.ai observes local activity]
  B --> C{Classify}
  C -->|Human| D[Human]
  C -->|AI| E[AI]
  C -->|Untracked| F[Untracked]
  D --> G[Deterministic Report]
  E --> G
  F --> G
  G --> H[Decisions: Devs / Leads / Managers / Execs]

Requirements

• VS Code 1.90.0 or later
• A Git repository workspace (recommended)
• Optional: VS Code Git extension (for best identity capture)

Install (VSIX)

1. Obtain the VSIX file (for example: bin/CodeRoot.ai-<version>.vsix)
2. Open VS Code
3. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
4. Run: Extensions: Install from VSIX…
5. Select the CodeRoot.ai .vsix file and confirm
6. Reload VS Code if prompted

PLACEHOLDER: GIF — Installing from VSIX

Quick start

Open a folder that is a Git repository, then run “CodeRoot: Initialize CodeRoot.” This creates a .coderoot/ folder for local tracking and reporting. By default, .coderoot is hidden in the Explorer to reduce noise; you can toggle its visibility any time.

PLACEHOLDER: GIF — Initialize CodeRoot (creates .coderoot/)

Quick Menu (your control center)

Open “CodeRoot: Settings / Quick Menu.” From a single place you can show or hide the .coderoot folder, switch the inventory mode (Modified vs All) to choose the report scope, open the .coderoot folder directly, or run an identity sweep on demand.

PLACEHOLDER: SCREENSHOT — Quick Menu (Visibility toggle, Inventory mode, CI section)

Generate and interpret reports

Run “CodeRoot: Generate Report.” The first view shows Human vs AI vs Untracked — the headline split most stakeholders care about. From there, explore by day, developer, and file.

• Human
  • Unified developer identities and stable counts
  • Per‑file ownership and recent change patterns
  • Trend lines to spot meaningful shifts
• AI
  • Where and how AI‑assisted work shows up in your repo
  • Compare proportions across files and days to see adoption and outcomes
• Untracked
  • Unknown or missing attribution surfaced for follow‑up
  • Use this list to improve data quality and reduce future Untracked

When enabled, time‑on‑task estimates can complement the composition view with episode‑based or duration‑based signals. These estimates are designed for trend‑level insights rather than precise timekeeping.

PLACEHOLDER: SCREENSHOT — Report overview (composition pie + totals) PLACEHOLDER: SCREENSHOT — Per‑developer table PLACEHOLDER: SCREENSHOT — Trends by day

\n### KPIs & Trend Slopes The report now surfaces a KPI block summarizing AI share today, rolling windows (7 & 30 days), deltas, and linear trend slopes. Slopes approximate daily change in AI share (fraction/day) over the chosen window via ordinary least squares.

Default slope windows: 7, 30. Configure additional windows (e.g. 14, 90) by setting:

// .coderoot/config.json
{
  "report": {
    "kpis": { "slope_windows": [7, 14, 30, 90] }
  }
}

Generated KPI fields (examples):

Slopes > 0 indicate increasing AI share; < 0 indicate decreasing share. Small magnitudes (e.g. 0.002) mean modest daily change (~0.2 percentage points/day). Combine slopes with deltas for narrative (e.g. “AI share accelerating vs 30‑day baseline”).

\n### Historical Compaction Long histories can bloat the dates map. Automatic weekly compaction groups older days into ~YYYY-Www buckets.

Config:

{
  "report": {
    "days_compaction": {
      "enabled": true,            // or omit to rely on auto threshold
      "keep_recent_days": 120,    // retain raw recent days
      "bucket": "weekly",        // future: other granularities
      "auto_threshold_days": 240  // if >240 days & not enabled, auto-compacts
    }
  }
}

When compaction applies, original daily keys beyond the recent window are replaced by weekly bucket keys prefixed with ~. Clients should detect ~ to style or expand if needed.

JSON Schema Artifact

Each report generation writes (or refreshes) a schema at:

.coderoot/v1/reports/schema/coderoot.report-0.4.schema.json

This draft-07 JSON Schema captures core fields (days, chart_data, kpis) and pattern properties for dynamic KPI names (e.g. ai_share_trend_slope_14). Integrate it with CI validation or typed generation pipelines. The schema is overwritten when its generated structure changes; treat it as authoritative for coderoot.report/0.4.

\n### KPI Markdown Table The Markdown report includes a 📌 KPIs section summarizing shares, deltas, and slopes. Values show both raw fractions (4 decimal places) and percentage forms for quick scanning.

\n### Attribution Audit Mode (Hardening / Optional) For deeper debugging you can enable an attribution audit that surfaces per-episode rationale (why something was classified AI, paste, human, or neutral). This is OFF by default to keep the payload lean.

Enable:

// .coderoot/config.json
{
  "report": {
    "attribution_audit": { "enabled": true }
  }
}

When enabled, each file entry gains:

{
  "attribution_audit": {
    "episodes": [
      {
        "decision": "ai|paste|human|neutral",
        "chars": 120,
        "loc": 5,
        "ai_chars": 120,
        "paste_chars": 0,
        "human_high_tcs_chars": 0,
        "neutral_ops": 0,
        "duration_ms": 850,
        "rationale": "ai_apply=1 ai_chars=120"
      }
    ]
  }
}

Use this to validate detector behavior or refine thresholds. Omit in automated downstream processing unless explicitly needed.

Legacy vs Net Lines & Inflation Warning

Two line modes exist:

• legacy (default): may inflate lines by counting every introduced line credit; retained for backward compatibility.
• net: reconstructs the buffer state and reports the net line distribution plus separate line_credits fields.

If you run a net-mode report (capturing credits) and then regenerate in legacy mode, a warning note appears when legacy lines exceed 3× the credited net lines:

warning: legacy line inflation ratio=3.25 (>3x). Consider enabling aggregation.mode_lines=net for accurate net buffer lines.

Switch to net mode to avoid over‑reporting and to anchor KPIs on actual remaining content.

Minimal configuration (optional)

You can tailor behavior in two places: the .coderoot/config.json file at the repository root and VS Code’s Settings for the CodeRoot extension.

Common .coderoot/config.json keys:

Relevant VS Code settings (Preferences → Settings → “CodeRoot”):

PLACEHOLDER: SCREENSHOT — Settings panel (CodeRoot section)

\n### Configuration Surface (H-009) Below is a consolidated reference of primary .coderoot/config.json keys (subset; for exhaustive defaults see src/config.ts). Optional keys absent from the file fall back to defaults.

Cross-check: The automated release checklist script (H-010) validates a subset of these keys for documentation drift.

Performance & Coverage Guardrails (H-006 / H-007)

Two optional (Phase 4) guard scripts reinforce stability:

Workflow:

1. After meaningful performance improvements or expected runtime shifts, refresh baseline with --update (records ms + Node version).
2. After coverage-increasing changes, optionally approve new baseline; on coverage dips justify with a note if acceptable (rare).
3. release-checklist.mjs --strict runs both and fails on hard regressions.

Outputs (JSON mode with --json):

// perf-threshold (ok)
{ "status": "ok", "ms": 820, "baseline_ms": 800, "delta_pct": 2.5 }
// coverage-guard (ok)
{ "status": "ok", "lines": 96.2, "branches": 95.8, "functions": 97.1, "statements": 96.0, "worstDrop": 0 }

Common workflows

\n### Show or hide the .coderoot folder Use the Quick Menu and select “Toggle .coderoot Visibility” to show or hide the folder in the Explorer. This keeps everyday work tidy while letting you inspect details when needed.

PLACEHOLDER: GIF — Toggle .coderoot visibility in Explorer

\n### Run an identity sweep Run “CodeRoot: Run Identity Sweep” to consolidate aliases (for example, multiple names or OS users mapping to one email). Unified identity ensures one person never shows up twice in reports.

PLACEHOLDER: SCREENSHOT — Identity sweep complete toast

\n### Generate reports in CI (optional) The extension can maintain .github/scripts/coderoot-report.mjs and reporter.mjs so you can run the same report in automation. For example:

node .github/scripts/coderoot-report.mjs "$GITHUB_WORKSPACE"

Create .github/.coderoot-ci.lock to opt out of script maintenance.

Note: CI script maintenance is OFF by default. To opt in, open the CodeRoot Quick Menu ("CodeRoot: Settings / Quick Menu") and enable the "CI Scripts Maintenance" toggle in the CI section. When the toggle is OFF the extension will not create or update any files under .github/ and will not register the .github/scripts watcher. The presence of .github/.coderoot-ci.lock will always disable maintenance even if the setting is enabled. Turning maintenance off does not delete existing .github files.

PLACEHOLDER: SCREENSHOT — CI Scripts Maintenance toggle in Quick Menu

Privacy and safety

CodeRoot.ai is local‑first. It does not contact servers. Reports are deterministic — identical inputs produce identical outputs — so you can trust comparisons over time and across machines.

Enterprise (optional)

For enterprise deployments (MCP, SaaS, or Hybrid), see the Enterprise Workplan index:

• docs/workplan/enterprise/README.md

Troubleshooting and FAQ

• “I don’t see .coderoot/.” Run “CodeRoot: Initialize CodeRoot” in the workspace root.
• “VS Code says Git isn’t available.” Install or enable the official Git extension for VS Code, then retry.
• “The report seems slow or inconsistent.” Make sure the folder is a Git repository and that .coderoot exists and is writable.
• “How do I change how names are shown?” Adjust identity_display in .coderoot/config.json or pick the preferred display mode in settings.

PCM Journal Migration (1.1.3 → 1.1.6)

Beginning with version 0.3.7, the writer emits schema_version 1.1.6 while the reader accepts 1.1.3–1.1.6 during a transitional window. (Version 0.3.6 briefly enforced 1.1.5‑only; this was relaxed to allow smoother upgrades and telemetry‑informed deprecation.) Advisory line/column ranges (best‑effort metadata) were introduced in 1.1.6; byte ranges remain authoritative for provenance.

When do you need migration?

You only need migration if you want past (pre‑upgrade) edits currently encoded as 1.1.3 / 1.1.4 / 1.1.5 to carry advisory line/col or consistent origin normalization. Fresh activity already emits 1.1.6 events automatically.

Options

1. Leave legacy lines untouched (simplest): They are ignored and your historical totals may reset at the upgrade boundary.
2. Run a migration to upgrade legacy lines in place:

Command Palette: CodeRoot: Migrate Legacy PCM Journals (prompts for Dry‑run or Apply)

• Terminal (dry‑run): node scripts/migrate-legacy-pcm.mjs
• Terminal (apply): npm run migrate:pcm

What the migration does

• Scans .coderoot/v1/files for journal segments (*.xform.jsonl and rotation files)
• Upgrades lines with schema_version 1.1.3 / 1.1.4 / 1.1.5 to 1.1.6
• Adds record_type: "pcm_event" if missing
• Maps legacy origin: "observed" to human (override via --map-observed=human|untracked|ai)
• Skips ops format and delete (they stay legacy; they don’t change composition)
• Creates a one‑time .pre-migration.bak per modified file

Safety / Dry‑run

Dry‑run (default) reports how many lines would be upgraded without writing changes. Use this first to estimate impact.

Example output

{
  "dry_run": false,
  "root": "D:/repo",
  "filesScanned": 12,
  "filesModified": 3,
  "linesExamined": 420,
  "linesUpgraded": 118,
  "malformedSkipped": 2,
  "observedMapped": 7
}

After migration

Re‑generate a report. Upgraded lines produce 1.1.6 events; consider optional advisory backfill:

node scripts/backfill-advisory-line-col.mjs --dry-run
node scripts/backfill-advisory-line-col.mjs --write

Advisory vs Authoritative Ranges (Summary)

Advisory line/col ranges are for UX; composition relies strictly on byte spans. Failures or skips (large file threshold) never block emission. See docs/spec/ADVISORY_RANGES.md.

Key points:

• Byte spans remain source of truth.
• Telemetry buckets (advisory_line_col_ms_le_*) track derivation latency.
• Counters track success, disabled feature flag, skipped large files, and failures.

Legacy text_sha Deprecation

Legacy non‑PCM text_sha events are ingested, counted (legacy_text_sha_seen), and trigger a one‑time console warning; removal planned once usage <0.1% (see docs/deprecations/text-sha-deprecation.md).

Rollback

Use the .pre-migration.bak files to restore a journal if needed (replace the upgraded file with its backup and re‑run report).

Automation

For CI or scripted workflows you can add a pre‑report step:

node scripts/migrate-legacy-pcm.mjs --write || true

This is optional and should be pinned to a commit to avoid re‑applying if you already migrated.

License and support

CodeRoot.ai is licensed commercially with free evaluation through December 31, 2025 (see LICENSE.md). For questions or feedback, contact support@coderoot.ai.