@shapeshift-labs/frontier-merge-metrics

Repo-shape and merge-conflict risk metrics for Git, Loom, and Frontier swarm workflows.

frontier-merge-metrics measures the project shapes that create merge and review bottlenecks before semantic merge has to rescue them. It can run as a standalone CLI over a Git checkout, or as a library over commit/change records produced by Loom, Frontier Swarm, CI, or another repository analytics pipeline.

• npm: @shapeshift-labs/frontier-merge-metrics
• source: siliconjungle/-shapeshift-labs-frontier-merge-metrics
• license: MIT

What It Measures

The package turns Git history into a source-free evidence object:

• hot files and hot directories
• time-ranged hotspot queries with current-versus-baseline trend labels
• same-file counterfactual collision risk between nearby commits
• observed merge-resolution signals from merge commits
• central file collisions for route tables, registries, config, barrels, and schemas
• generated, lockfile, fixture, and snapshot churn
• global CSS versus scoped CSS/module surfaces
• co-change edges that reveal hidden coupling
• recommended repo-shape interventions

The goal is not to replace semantic merge. The goal is to reduce how often semantic merge is needed by making project architecture friendlier to parallel work.

Semantic Work Feedback

Repo history is only one input. During a Loom or swarm run, agents can also emit semantic work events as they attempt, rebase, gate, and apply patches. frontier-merge-metrics turns those events into a feedback object the coordinator can use on the next refill:

• regions that should not be edited concurrently
• preferred semantic lease keys
• task surfaces that should be split narrower
• refactor candidates such as central registries, broad fixtures, and global style regions
• correlated region pairs that should be routed together or deliberately separated

This is the loop:

agent attempt -> changed semantic regions -> admission outcome
      -> correlated-work report -> routing / lease / refactor hints
      -> next task refill

Advanced Hotspot Queries

The base reports answer "what is the shape of this repo or run?" Hotspot queries answer "what should the coordinator do next for this time window?"

A hotspot query can run over Git commits or semantic work events and returns the same report kind:

• frontier.mergeMetrics.hotspotQueryReport
• current and comparison time windows
• hot regions with current metrics, previous metrics, trend, risk score, and reasons
• hot edges for co-changing files or correlated semantic regions
• compact feedback for routing, leases, split-task prompts, refactor candidates, gate candidates, and rising hotspots

Use this report for refill decisions and dashboards. The markdown renderer is a human summary; the JSON feedback fields are the automation contract.

CLI

npm exec --package @shapeshift-labs/frontier-merge-metrics -- frontier-merge-metrics \
  --repo . \
  --max-commits 200 \
  --max-file-snapshots 500 \
  --pair-window 20 \
  --out reports/merge-metrics.json \
  --report reports/merge-metrics.md

Analyze a corpus:

frontier-merge-metrics \
  --repo /tmp/react \
  --repo /tmp/vite \
  --repo /tmp/prettier \
  --out reports/corpus.json \
  --report reports/corpus.md

Analyze semantic work events from a live run:

frontier-merge-metrics \
  --events agent-runs/current/semantic-work.jsonl \
  --out reports/correlated-work.json \
  --report reports/correlated-work.md

Query the current Git hotspot window against a previous window:

frontier-merge-metrics \
  --repo . \
  --query-hotspots \
  --since 2026-06-15T00:00:00.000Z \
  --until 2026-07-01T00:00:00.000Z \
  --compare-since 2026-06-01T00:00:00.000Z \
  --compare-until 2026-06-15T00:00:00.000Z \
  --out reports/hotspots.json \
  --report reports/hotspots.md

Query semantic work events from a swarm run:

frontier-merge-metrics \
  --events agent-runs/current/semantic-work.jsonl \
  --query-hotspots \
  --last-days 7 \
  --top-hotspots 25 \
  --out reports/work-hotspots.json

Library API

import { analyzeRepoShape } from '@shapeshift-labs/frontier-merge-metrics';

const report = analyzeRepoShape({
  repository: 'example',
  commits: [
    {
      hash: 'a1',
      files: [{ path: 'src/routes.ts', additions: 3, deletions: 1 }]
    },
    {
      hash: 'b2',
      files: [{ path: 'src/routes.ts', additions: 2, deletions: 0 }]
    }
  ]
});

Query Git-like commit records in memory:

import { queryMergeHotspots } from '@shapeshift-labs/frontier-merge-metrics';

const report = queryMergeHotspots(input, {
  timeRange: {
    since: '2026-06-15T00:00:00.000Z',
    until: '2026-07-01T00:00:00.000Z',
    basis: 'commit-date'
  },
  compareTo: {
    since: '2026-06-01T00:00:00.000Z',
    until: '2026-06-15T00:00:00.000Z'
  },
  includeInactive: true,
  topHotspots: 50
});

console.log(report.feedback.risingHotspotKeys);

Analyze semantic merge work directly:

import {
  analyzeCorrelatedWork,
  queryCorrelatedWorkHotspots
} from '@shapeshift-labs/frontier-merge-metrics';

const report = analyzeCorrelatedWork([
  {
    runId: 'run-42',
    taskId: 'parser-recovery-a',
    agentId: 'agent-a',
    lane: 'parser',
    changedPaths: ['src/parser.ts'],
    changedRegions: [
      { kind: 'function', file: 'src/parser.ts', symbol: 'parseNode' }
    ],
    outcome: 'conflict'
  },
  {
    runId: 'run-42',
    taskId: 'parser-recovery-b',
    agentId: 'agent-b',
    lane: 'parser',
    changedPaths: ['src/parser.ts'],
    changedRegions: [
      { kind: 'function', file: 'src/parser.ts', symbol: 'parseNode' }
    ],
    outcome: 'stale'
  }
]);

console.log(report.feedback.avoidConcurrentRegionKeys);

const hotspots = queryCorrelatedWorkHotspots(report.events, {
  timeRange: { lastDays: 7, basis: 'completed-at' },
  topHotspots: 25
});

console.log(hotspots.feedback.gateCandidateRegionKeys);

Node Git collector:

import {
  analyzeCorrelatedWorkEventsFile,
  analyzeGitRepository,
  queryGitRepositoryHotspots
} from '@shapeshift-labs/frontier-merge-metrics/node';

const report = analyzeGitRepository('/path/to/repo', {
  maxCommits: 300,
  maxFileSnapshots: 500,
  pairWindow: 25,
  since: '2026-06-01T00:00:00.000Z',
  until: '2026-07-01T00:00:00.000Z'
});

const liveReport = analyzeCorrelatedWorkEventsFile('agent-runs/current/semantic-work.jsonl');

const gitHotspots = queryGitRepositoryHotspots('/path/to/repo', {
  timeRange: {
    since: '2026-06-15T00:00:00.000Z',
    until: '2026-07-01T00:00:00.000Z'
  },
  compareTo: {
    since: '2026-06-01T00:00:00.000Z',
    until: '2026-06-15T00:00:00.000Z'
  },
  includeInactive: true
});

For queue-time scans, keep maxCommits and maxFileSnapshots small. For scheduled repo-shape reports, increase them and keep the generated JSON evidence.

Report Semantics

counterfactualCollisionRate asks: if nearby commits had been developed as parallel branches, how often would they have touched at least one same file?

centralCollisionRate narrows that to likely coordination bottlenecks such as routes.ts, router.ts, registry.ts, schema.ts, config.ts, and index.ts.

mergeResolutionEventRate is different. It is based on observed merge commits where the merge result differs from every parent on the same path. This is evidence of integration pressure, but not proof that a platform PR conflict happened.

parallelismScore is a heuristic 0-100 score. Higher means the observed history is more likely to support independent work. It is intentionally conservative: it highlights risks to investigate, not proof that a repo will or will not merge automatically.

Time Windows

Hotspot query windows are half-open: since <= event time < until. That makes adjacent windows safe to compare without double-counting boundary events.

For Git collection, --since and --until are passed to git log before pathspec filters. The collector records both author date and commit date; hotspot queries default to commit-date because Git's date filtering is commit-time based. The base repo-shape report still says "sampled commits" because maxCommits can truncate a period.

For semantic work events, queries default to completed-at, falling back to startedAt. Events without timestamps are included only in unbounded queries.

Loom And Swarm Integration

Loom and Frontier Swarm can feed this package directly from run logs, queue manifests, changed-path indexes, semantic regions, or Git workspaces:

• before a swarm run, use repo-shape metrics to find hot ownership lanes
• during a run, append semantic work events with runId, taskId, agentId, lane, changedPaths, changedRegions, and an admission outcome
• on every refill, query the event stream and feed feedback.avoidConcurrentRegionKeys, feedback.preferredLeaseKeys, feedback.splitTaskRegionKeys, feedback.refactorCandidateRegionKeys, feedback.gateCandidateRegionKeys, and feedback.risingHotspotKeys into routing
• after a run, use interventions to split central files, scope CSS, shrink fixtures, or move generated outputs out of review
• attach run, job, lane, and region metadata in your own input records when correlating reports with swarm outcomes

The root API is structural and does not require Git. The Node subpath and CLI are convenience collectors for ordinary repositories.

Evidence

This repo includes a bounded public-repository evidence pass under evidence/:

• public-js-ts-corpus-2026-06-29.json
• public-js-ts-corpus-2026-06-29.md
• public-js-ts-trends-2026-06-29.md

Those reports sample recent history from Astro, Hono, Prettier, Svelte, and Vite to show the metrics on real projects.