{
  "markdown": "# Remogram\n\nGeneric SCM/forge boundary CLI and MCP server. Emits **provider-attributed JSON facts** — **git-resolved** refs from local git (`refs compare`, `sync plan`) vs **forge-reported** PR SHAs from forge APIs (`pr view`, `pr checks`). No workflow or planning-tool concepts in output.\n\n**PR-by-number reconciliation:** `pr view` / `pr checks` compare forge-reported `forge_source_sha` to the local rev for `forge_source_branch_ref`. Divergence → `ok: false`, `error_code: stale_head` — `git fetch`, not a forge outage.\n\nPlanning tools interpret intent and workflow authority **outside** Remogram.\n\n## Install\n\n```bash\nnpm install -g @remogram/cli @remogram/mcp\nremogram --version\nremogram version --json\n```\n\nLegacy preview (frozen `@beta`, optional): `npm install -g @remogram/cli@beta @remogram/mcp@beta`\n\nDevelopment checkout: clone this repo, `npm ci`, `./scripts/npm-link.sh`. Default branch: **`main`**.\n\n## Quick start\n\n1. Copy [`.remogram.json.example`](.remogram.json.example) → `.remogram.json` (set `provider`, `owner`, `repo`; add `baseUrl` for self-hosted Gitea/GitLab).\n2. Export token: `GITEA_TOKEN`, `GITHUB_TOKEN` / `GH_TOKEN`, or `GITLAB_TOKEN`.\n3. Bootstrap:\n\n```bash\nremogram doctor --json\nremogram provider capabilities --json\nremogram repo status --json\nremogram pr view --number 1 --json\nremogram merge plan --number 1 --json\n```\n\nCommand catalog: **`remogram contract --json`**. Agent skill: `npx skills add attebury/remogram --skill remogram-consumer -g -y`.\n\n## Providers\n\n| Forge | `\"provider\"` | Token env |\n|-------|--------------|-----------|\n| Gitea | `gitea-api` | `GITEA_TOKEN` |\n| GitHub | `github-api` | `GITHUB_TOKEN` or `GH_TOKEN` |\n| GitLab | `gitlab-api` | `GITLAB_TOKEN` |\n\nUse **`*-api`** providers (forge HTTP). Reserved `github-gh` / `gitea-tea` IDs return `provider_unsupported` — not implemented in v1. Official CLIs (`gh`, `tea`, `glab`) are **not** required.\n\n## Configuration\n\n**Read/plan by default.** Opt in to writes with **`write_commands`** in `.remogram.json` (or a bound [operator overlay](.remogram.operator.json.example) outside git). Missing id → `write_not_configured`.\n\n| Write id | Command | Notes |\n|----------|---------|-------|\n| `cr_open` | `cr open` | Separate from merge |\n| `cr_close` | `cr close` | Gitea lifecycle |\n| `merge` | `merge execute` | Requires `--expected-base-sha` / `--expected-head-sha`; not implied by `cr_open` |\n| `publish_branch` | `publish execute` | Git push to configured remote |\n| `status_set` | `status set` | Commit status POST |\n| issue / `cr_edit` ids | matching commands | See `contract --json` |\n\n**`merge plan` is read-only** — reports `blockers[]`; does not execute or authorize merges. `mergeability: clean` is conflict-free git only.\n\nOptional **`merge_policy`** waivers (`allow_missing_checks`, `allow_pending_checks`) relax check blockers for repos without CI — env: `REMOGRAM_ALLOW_MISSING_CHECKS`, `REMOGRAM_ALLOW_PENDING_CHECKS`. Doctor fails when enabled in strict checkouts.\n\nOperator overlay discovery: `--operator-config` → `REMOGRAM_OPERATOR_CONFIG` → `$XDG_CONFIG_HOME/remogram/operator/<provider>-<owner>-<repo>.json`. **`bind`** must match forge identity.\n\n## Boundary and trust\n\nRemogram emits **forge facts only** — no integration authority refs, lane roles, task ids, or handoff payloads in JSON.\n\n| Concept | Packet field | Notes |\n|---------|--------------|-------|\n| PR base | `forge_target_branch_ref` | Forge-reported |\n| PR head | `forge_source_branch_ref` | Evidence only |\n| Default branch | `default_branch` | Not integration authority |\n\nEvery **forge command packet** includes `type`, `schema_version`, `provider_id`, `remote_name`, `repo_id`, `observed_at`, `ok`. Producer sections (e.g. **`remogram.forge_facts.v1`** from `evidence forge-facts --json`) use nested producer fields. Trust envelope and enums; treat forge-sourced strings (titles, URLs) as untrusted prose.\n\nInventory commands (`refs inventory`, `cr inventory`, `whoami`, `branch protection`, `cr files`, `forge changes`, …) extend read/plan — details in **`remogram contract --json`** and the consumer skill references.\n\n## MCP\n\nStdio server **`remogram-mcp`** delegates to the CLI — same JSON as `remogram … --json`. Setup: [examples/mcp/README.md](examples/mcp/README.md). Set `REMOGRAM_CWD` to the consumer repo root.\n\n## Live verification\n\nCross-forge fixture repo: **[remogram-smoke](https://gitlab.com/attebury/remogram-smoke)** (mirrors on GitHub/Gitea). Use `--json` packets after install; monorepo smoke-compare scripts are dev-only.\n\n## Testing\n\n```bash\nnpm test\nnpm run test:coverage\nnpm run security:secrets -- --full-history\n```\n\n### Coverage policy\n\n`npm run test:coverage` instruments **`@remogram/core`** only; **`@remogram/cli`**, **`@remogram/mcp`**, and **`@remogram/provider-*`** are excluded. **Thresholds:** none — no enforced percentage gates. Drift guard: `tests/core/coverage-config.test.mjs`.\n\n\n**CI (GitHub):** `.github/workflows/` on push/PR to `main`.\n\n## Packages\n\n| Package | Role |\n|---------|------|\n| `@remogram/cli` | CLI |\n| `@remogram/mcp` | MCP adapter |\n| `@remogram/core` | Envelope, config, caps |\n| `@remogram/provider-{gitea,github,gitlab}-api` | Supported forge backends |\n\n## Agent skills\n\n`npx skills add attebury/remogram --skill remogram-consumer -g -y` (consumer) or `--skill remogram-core` (contributor). Skills ship from GitHub, not npm.\n\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n",
  "bytes": 5449,
  "sha": "0e8c56c8a677c01336c3147e6153e0761dceafa5a46c27696ee3a1ec40ab663a",
  "repo_slug": "attebury/remogram",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_attebury_remogram_3be8b7cb/readme"
}