# repo-flow

`repo-flow` is a Linux x64 command-line tool and Pi package for moving code safely between an authoritative downstream repository and a Git upstream. It provides deterministic inbound synchronization, guarded backflow artifacts, local upstream-PR verification, and machine-readable evidence.

The current adapter targets AGS-authoritative downstream repositories through `ags-cli --json`. Git remains the authority for commits and refs. Upstream review stays Git-only and does not require AGS credentials.

## Install

The public npm package requires Bun 1.3.14 or newer and does not bundle or redistribute the Bun standalone runtime. Registry `latest` remains 0.1.4 until the 0.1.5 candidate in this source is published and read back; do not treat `package.json` as registry evidence.

```bash
bun --version
npm install --global @yoyooyoooyoooo/repo-flow@0.1.4
repo-flow --version --json
```

To load the bundled Agent Skills in Pi:

```bash
pi install npm:@yoyooyoooyoooo/repo-flow@0.1.4
```

Pi package installation does not promise to add package bins to the Agent shell `PATH`. Each bundled Skill therefore resolves its own package root from the absolute `SKILL.md` location supplied by Pi and invokes that root's `dist/repo-flow.js` with Bun. It does not search `PATH` or fall back to a global `repo-flow`.

The npm package contains a Bun-targeted JavaScript entry and three Skills:

```text
upstream-sync
merdi-backflow-submit
upstream-backflow-pr
```

Internal standalone binaries, release manifests, rollback evidence, and production deployment are maintained separately and are not part of the npm package or npm publish gate.

## Repository Profile

Run commands from a repository root containing `.repo-flow.yaml`. A strict portable profile has this shape:

```yaml
schema: repo-flow.profile.v1
repository: owner/downstream
refs:
  main: main
  upstream_ruler: upstream-main
  upstream_absorbed: sync/upstream-absorbed
  upstream_active: sync/upstream/active
backflow:
  product_paths:
    - src/
  downstream_only_paths:
    - .agents/
```

Existing schema-1 deployments remain read-only by default. A repository owner may explicitly promote that legacy profile for the TypeScript writer by adding:

```yaml
runtime:
  writer: repo-flow
```

Promotion is fail-closed: the writer value must be exact, the repository refs and Backflow policy must validate, and secrets or credential-shaped keys are rejected. Host credentials, provider URLs, tokens, and machine paths do not belong in the portable profile consumed by the new writer.

## Commands

The accepted long-term Agent-facing surface is:

```bash
repo-flow --version --json
repo-flow status --json
repo-flow sync run --json
repo-flow backflow create --ags-pr <number> --json
repo-flow backflow consume <artifact> --json
repo-flow backflow continue [--allow-empty-resolution] --json
repo-flow backflow status --json
repo-flow upstream-pr verify --json
```

The 0.1.5 source candidate routes only the command closure above. It is not an installable registry fact until publish/readback. Compatibility/conformance primitives, `backflow reconcile`, qualification faults, and evidence tooling are available only from the separate internal/test composition and are not part of the npm public surface. Removed public routes fail with the structured `public_route_removed` envelope. See the [end-to-end operating model](docs/product/end-to-end-operating-model.md) and [ADR 0002](docs/adr/0002-freeze-public-surface-before-release.md).

Public observation is fail-closed but diagnostic: a stopped workflow returns a stable phase/error, `first_wrong_state`, retained Unit/Batch/Q/PR/fence identity, and one `next_action`. Late AGS failures do not erase verified Git facts. Inbound maps only `OPEN` to review, `MERGED` to resume closeout, and rejects `CLOSED` without merge or unknown states. Backflow keeps read failures and protocol damage distinct from a healthy `q_remote`; durable pending output exposes non-sensitive fence evidence but never the claim token, while a visible PR without a fence is sent through `continue_backflow` to bind the existing exact PR before it can be called ready.

### Inbound

`sync run` consumes the mirrored upstream ruler, allocates or resumes one frozen unit, derives exact coverage, acquires a `unit + candidate` Git-CAS fence, publishes at most one downstream PR, and closes only after exact readback. An unresolved create claim is observed indefinitely rather than taken over on a timer; while that fence exists, accepted-main movement cannot rebuild or move the candidate before the original claim is settled, and a PR first observed as merged is bound by number before closeout. Initial cursor advancement requires accepted `main == candidate`; once the cursor reaches the frozen target, that durable fact permits a Git-only active-release retry without re-reading AGS or revalidating a later ruler/main. It does not accept environment, deployment, unit, SHA, or coverage arguments from the operator.

### Backflow

`backflow create` derives one checksummed Git-bundle artifact from an accepted downstream PR. `backflow consume` runs in a controlled upstream workspace and creates or resumes the canonical single-parent Q branch. Q PR publication first acquires a per-Batch `Batch + current Q` Git-CAS fence and binds the exact AGS PR number after readback; a same-Batch Q rebuild can migrate that binding only when the same PR number shows the new head. An unresolved claim is reported as `pr_create_pending` and never triggers a timed second create. The artifact and its verified handoff bind the source PR, source range, upstream anchor, Batch identity, and checksum.

### Upstream Review

`upstream-pr verify` uses only the current Git repository, base/head refs, tracked diff, and Q commit structure. It does not construct an AGS adapter or read a downstream profile. Repository-specific tests and the decision to create or merge a real upstream PR remain with the upstream owner.

## Security Boundary

- System Git performs all object and ref operations.
- Downstream AGS facts come from the installed `ags-cli` JSON interface.
- RepoFlow does not read AGS secret files or Forgejo credentials.
- Unknown external effects require exact readback; commands do not blind-retry writes.
- The npm package has no install, preinstall, or postinstall lifecycle scripts.
- The npm tarball does not contain a Bun standalone binary; Bun is an explicit runtime prerequisite.
- Pi Skills can instruct an agent to run commands with the user's authority; review them before enabling the package.

## Product And Architecture

Start with the [end-to-end operating model](docs/product/end-to-end-operating-model.md) for background, roles, user stories, both code-flow directions, authority boundaries, delivery stages, and claim limits. Current fact writers live in [SSoT](docs/ssot/README.md); runtime boundaries live in [Architecture](docs/architecture/repo-flow.md).

## Development

The canonical source uses Bun and TypeScript:

```bash
bun install --frozen-lockfile
bun run check
bun run test:temp-lifecycle
bun run package:candidate
bun run test:package-install
```

Conformance uses isolated repositories and the same compiled binary. Fixture runs and simulated upstream PRs prove only their listed properties; they do not claim a real upstream provider effect.

## License

MIT. See [LICENSE](LICENSE).