Add optional repo intelligence module using GitHub CLI-backed history sync

[stackbilt-admin]

Problem

Charter currently focuses on local-first repo governance and deterministic codebase analysis:

• ADF context loading
• commit validation
• drift checks
• blast-radius analysis
• surface extraction
• audit/reporting workflows
• MCP project context exposure

That gives agents and developers a strong view of the repo’s current local state.

However, Charter does not yet have a way to understand the repo’s development history:

• issue lifecycle
• PR lifecycle
• review behavior
• release cadence
• maintainer response patterns
• stale or recurring problem areas
• decision archaeology from comments and linked PRs
• contributor concentration / bus-factor signals

For agent workflows, this is a missing layer. Agents can see the repo’s files and governance rules, but not the historical context of how the project evolved.

Why this matters

GitHub issue and PR history is effectively a semi-structured institutional memory layer.

A repo’s history can answer questions like:

• Is this repo actively maintained?
• What areas repeatedly break?
• Which contributors actually drive development?
• Are issues being triaged, ignored, or churned?
• How long do PRs take to review and merge?
• Which architectural decisions were debated in issues/PRs?
• Are releases regular or sporadic?
• Is the project becoming healthier or more chaotic over time?
• What risks should an AI agent know before making changes?

This would complement Charter’s existing local analysis commands:

• charter validate
• charter drift
• charter blast
• charter surface
• charter audit
• charter adf bundle
• charter serve

The goal is not to make Charter dependent on GitHub, hosted services, or network access by default.

The goal is to provide an optional, explicitly invoked repo intelligence module that can generate local development-history artifacts for humans and AI agents.

Key design constraint

Charter’s core posture should remain:

• local-first
• deterministic where possible
• no required network calls
• no credentials stored by Charter
• no product/service dependency for normal governance usage

Therefore, this feature should not embed GitHub auth or require Charter to manage tokens.

Proposed implementation direction

Use the user’s installed GitHub CLI (gh) as the MVP transport layer.

This preserves Charter’s local-first/auth-minimal posture:

• Charter does not manage GitHub OAuth.
• Charter does not store GitHub tokens.
• Existing gh auth login handles credentials.
• Public/private repo access follows the user’s existing GitHub CLI permissions.
• Network calls only occur when the user explicitly invokes a repo-intel command.
• Advanced GitHub endpoints can still be accessed through gh api --paginate.

Conceptually:

charter repo sync
  ↓
detect gh CLI
  ↓
verify gh auth/status when needed
  ↓
run gh api --paginate ...
  ↓
normalize GitHub responses
  ↓
write local .charter/repo-intel artifacts
  ↓
generate metrics, dossiers, and optional ADF modules

[stackbilt-admin]

If gh is unavailable, Charter should fail with a clear actionable message:

GitHub CLI is required for repo intelligence sync.

Install:
  https://cli.github.com/

Then authenticate:
  gh auth login

Desired shape

Add an optional repo intelligence capability, likely as a separate package and CLI namespace.

Possible package structure:

packages/
  repo-intel/       # normalized repo history model + analysis
  github-gh/        # GitHub CLI adapter / gh transport

Or, if keeping the first implementation consolidated:

packages/
  repo-intel/
    src/
      providers/
        gh/
      normalize/
      metrics/
      reports/
      adf/

This should not live in packages/core, because core should remain focused on shared schemas, sanitization, and error contracts rather than accumulating provider-specific network behavior.

Proposed CLI commands

Possible namespace:

charter repo sync
charter repo dossier
charter repo health
charter repo timeline
charter repo decisions
charter repo adf

Alternative namespace:

charter intel sync
charter intel report
charter intel risks
charter intel timeline
charter intel decisions

Initial MVP command shape:

charter repo sync <owner/repo> --since <date>
charter repo health <owner/repo> --format json
charter repo dossier <owner/repo> --format markdown
charter repo adf <owner/repo> --write .ai/repo-history.adf

Convenience behavior:

charter repo sync

When run inside a git repository, Charter may infer owner/repo from origin.

Data to collect

MVP sync should collect enough history to reconstruct repo development patterns.

Potential source data:

issues
pull requests
issue comments
PR reviews
PR review comments
issue/PR timeline events
commits
releases
labels
milestones
contributors
linked references

Likely gh commands:

gh api repos/{owner}/{repo}/issues --paginate
gh api repos/{owner}/{repo}/pulls --paginate
gh api repos/{owner}/{repo}/releases --paginate
gh api repos/{owner}/{repo}/contributors --paginate

For deeper per-item hydration:

gh api repos/{owner}/{repo}/issues/{number}/comments --paginate
gh api repos/{owner}/{repo}/issues/{number}/timeline --paginate
gh api repos/{owner}/{repo}/pulls/{number}/reviews --paginate
gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate

Notes:

• GitHub’s issues endpoint includes both issues and pull requests; normalization should separate true issues from PR-backed issues.
• Timeline/review/comment hydration may need a depth flag to avoid excessive sync volume.
• Large repos should support date bounds and/or limits.

Sync modes

Suggested sync modes:

charter repo sync --lite
charter repo sync --full
charter repo sync --since 2026-01-01
charter repo sync --max-items 500

Possible behavior:

Lite sync

Collect:

• issues
• pull requests
• releases
• contributors
• labels
• milestones

Skip:

• full comments
• timeline events
• review comments

Full sync

Collect:

• comments
• reviews
• review comments
• timeline events
• linked references where feasible

Incremental sync

Use local sync state to avoid refetching everything:

.charter/
  repo-intel/
    github-sync-state.json

State should track:

{
  "repo": "Stackbilt-dev/charter",
  "lastSyncedAt": "2026-05-05T00:00:00Z",
  "since": "2026-01-01T00:00:00Z",
  "transport": "gh",
  "schemaVersion": 1
}

Local artifact layout

Suggested output:

.charter/
  repo-intel/
    github-sync-state.json
    raw/
      issues.jsonl
      pull-requests.jsonl
      issue-comments.jsonl
      review-comments.jsonl
      timeline-events.jsonl
      releases.jsonl
      contributors.jsonl
      labels.jsonl
      milestones.jsonl
    derived/
      metrics.json
      repo-health.json
      timeline.json
      decision-candidates.jsonl
      contributor-map.json
      stale-risks.json
    reports/
      dossier.md
      health.md
      timeline.md
      risks.md
      decisions.md

Optional ADF output:

.ai/
  repo-history.adf
  repo-risks.adf
  repo-decisions.adf

Derived metrics

The first useful metrics should be deterministic and explainable.

Examples:

issue_count_open
issue_count_closed
stale_issue_count
median_time_to_first_response
median_time_to_close
pr_count_open
pr_count_merged
pr_count_closed_unmerged
median_time_to_merge
median_review_latency
review_comment_volume
reopen_count
label_distribution
release_interval_days
commit_frequency
contributor_concentration
maintainer_response_ratio
hot_threads_by_comment_count
decision_candidate_threads

Reports

The feature should produce both machine-readable and human-readable outputs.

Possible reports:

repo-health.json
repo-dossier.md
repo-timeline.md
repo-risks.md
repo-decisions.md
repo-maintenance-brief.md

Example report sections:

# Repository Development Dossier

## Executive Summary

## Development Timeline

## Maintenance Health

## Issue Triage Patterns

## Pull Request Flow

## Review Bottlenecks

## Contributor Map

## Recurring Problem Areas

## Decision Threads

## Release Cadence

## Risks and Recommendations

ADF integration

The strongest integration point is ADF.

charter repo adf or charter intel adf could generate an on-demand ADF module from repo history.

Example:

# repo-history.adf

ROLE [advisory]:
  - You are reading historical development context for this repository.

CONTEXT [load-bearing]:
  - Recent development velocity: ...
  - Most active areas: ...
  - Repeated risk themes: ...
  - Recent maintainer decisions: ...

CONSTRAINTS [advisory]:
  - Treat stale issues older than N days as weak evidence unless recently referenced.
  - Prefer merged PRs and maintainer comments over unreviewed comments.
  - Treat raw comments as historical context, not current truth, unless confirmed by recent commits or releases.

STATE [advisory]:
  NOW:
    - ...

  NEXT:
    - ...

  REMEMBER:
    - ...

Potential manifest triggers:

github
issues
pull requests
repo history
maintenance
stale
contributors
release cadence
decision history
architecture history

This lets agents load repo history only when relevant, instead of always bloating context.

MCP integration

If Charter’s MCP server exposes project context, this module could later expose repo intelligence tools such as:

getRepoHealth
getRepoTimeline
getRecentIssueThemes
getDecisionThreads
getContributorMap
getStaleRisks

This would allow Claude Code or other agents to ask for repo history without loading all raw issue/PR data.

Digital CSA / StackBilt Compass integration

This also creates a clean bridge to Digital CSA / Compass.

Possible flow:

GitHub repo
  ↓
charter repo sync
  ↓
local repo-intel ledger
  ↓
ADF repo-history module
  ↓
charter serve / MCP
  ↓
Digital CSA governance memory

This would let CSA consume historical development evidence when evaluating:

• governance maturity
• architectural drift
• recurring risks
• unresolved decisions
• maintainer overload
• release-readiness
• repo due diligence

Non-goals for MVP

The MVP should avoid turning this into a full SaaS/dashboard.

Non-goals:

• no hosted sync service
• no database requirement
• no token storage by Charter
• no embedded GitHub OAuth
• no LLM-required analysis
• no mandatory GitHub dependency for normal Charter usage
• no automatic network calls during normal charter validate, doctor, drift, blast, surface, or adf commands
• no background sync

Error handling

If gh is not installed:

GitHub CLI is required for repo intelligence sync.

Install:
  https://cli.github.com/

Then authenticate:
  gh auth login

If gh is installed but not authenticated and the repo requires auth:

GitHub CLI is installed, but authentication is required for this repo.

Run:
  gh auth login

If rate limits or API failures occur:

GitHub sync failed before completion.

Partial data may exist under:
  .charter/repo-intel/raw/

Re-run the command after the rate limit resets or use:
  charter repo sync --since <date>

MVP proposal

Phase 1: GitHub CLI-backed sync

• Add packages/repo-intel
• Add gh transport/adapter
• Detect whether gh is installed
• Infer owner/repo from git remote when possible
• Fetch public repo issues, PRs, releases, labels, milestones, contributors
• Normalize GitHub responses
• Write JSONL artifacts under .charter/repo-intel/raw/
• Compute basic deterministic metrics
• Emit .charter/repo-intel/derived/repo-health.json

Phase 2: Reports and ADF

• Add Markdown dossier generation
• Add repo-health.md
• Add repo-timeline.md
• Add explicit ADF module generation
• Support .ai/repo-history.adf
• Add manifest trigger suggestions

Phase 3: Deeper history

• Add issue comments
• Add PR reviews
• Add PR review comments
• Add timeline events
• Add decision-thread candidate extraction
• Add contributor/risk maps
• Add incremental sync state

Phase 4: MCP / CSA export

• Add MCP tools for repo intelligence
• Add Digital CSA-compatible export format
• Add governance-memory handoff artifact

Open questions

• Should the command namespace be charter repo, charter intel, or charter history?
• Should the package be named repo-intel, history, archaeology, or something else?
• Should GitHub CLI transport live inside repo-intel initially or in a separate github-gh package?
• Should outputs default to .charter/repo-intel/ or require --write?
• Should ADF generation be explicit only?
• How much historical data should be pulled by default for large repos?
• Should charter repo sync infer the current repo from origin by default?
• Should full comment/timeline hydration require --full?
• Should direct GitHub API / Octokit support ever be added, or should gh remain the default boundary?

Acceptance criteria

• User can run an explicit command against a public GitHub repo using local gh.
• Charter does not store GitHub credentials.
• Charter does not require GitHub credentials for normal local-first workflows.
• Charter does not make network calls unless a repo-intel command is explicitly invoked.
• If gh is missing, Charter fails with a clear actionable message.
• If repo can be accessed through gh, Charter fetches repo history data.
• Data is written as local JSONL artifacts.
• A deterministic repo-health.json is produced.
• A human-readable Markdown dossier can be generated.
• Existing Charter commands remain offline/local-first.
• Feature is documented as optional repo intelligence.