# How RepoCharter works

RepoCharter is local-first. It separates repository facts, developer decisions, and
durable filesystem changes so a coding agent cannot quietly turn an assumption into
project truth.

## Lifecycle

1. **Inspect** — `init` and `check` perform bounded static inspection. They respect
   `.gitignore`, hard-exclude secret-bearing files, redact captured command evidence,
   and never execute repository scripts.
2. **Select and resume** — a new setup records one primary agent and optional secondary
   agents in `.repo-charter/manifest.json`. `resume` reinspects changed safe paths before
   relying on an earlier snapshot.
3. **Grill** — the active coding agent uses the handoff to ask the complete unblocked
   decision frontier in rounds. It recommends answers, resolves contradictions, and
   obtains explicit shared-understanding confirmation. Raw chat is not persisted.
4. **Specify and preview** — an approved specification supplies confirmed decisions,
   selected agents, verification depth, proposed artifacts, conflict decisions, and
   developer approval. The internal skill workflow generates the canonical documents
   and previews every target before writing.
5. **Approve and apply** — missing or unchanged tool-owned files may be approved
   together. Project-owned or modified files require per-file preservation or explicit
   reconciled content. Approved writes use the shared atomic writer.
6. **Validate and hand off** — `check` is read-only. It reports integrity errors,
   advisory warnings, observed check outcomes, artifact status, blockers, and the first
   unchecked task.

## Manual CLI and skill flow

```bash
# Start a bounded inspection/session.
repo-charter init ../target --primary-agent codex --json

# Resume after an interruption or changed files.
repo-charter resume ../target --json

# After the developer has approved a safe specification, preview/apply through the
# stable CLI workflow contract (the installed skill wrapper calls these operations).
repo-charter workflow preview ../target approved-spec.json --json
repo-charter workflow apply ../target approved-spec.json approvals.json --json

# Inspect setup integrity without writing.
repo-charter check ../target --json

# Explicitly compare an approved safe anchor with current context. This is read-only;
# in Git repositories it discloses and runs only read-only Git observations.
repo-charter drift-check ../target --json

# After developer review, explicitly refresh the safe anchor.
repo-charter drift-acknowledge ../target --json
```

The CLI exposes stable `workflow preview` and `workflow apply` operations for the
approved-specification path. The installed skill wrapper calls the published CLI through
that contract; it does not import repository-relative source modules or maintain a
second implementation. If the CLI is absent, the skill asks the developer to approve an
explicit install or versioned `npx` invocation and never downloads it silently.

## Workspace visibility

Before generation, the developer confirms one mode:

- `local-planning`: commit `AGENTS.md`; keep `PLAN.md`, `TODO.md`, selected adapters,
  rules, and `.repo-charter/` local.
- `shared-planning`: commit `AGENTS.md`, planning documents, and selected adapters;
  keep `.repo-charter/` local.

RepoCharter previews its managed ignore block and never automatically untracks files.

## Context drift

After an approved skill application, RepoCharter records a local safe drift anchor:
repository snapshot metadata, hashes of applicable planning documents, and no source
bodies, patches, transcripts, or credentials. `drift-check` compares the current safe
snapshot with that anchor. When explicitly invoked in a Git repository, it additionally
reports the current revision plus committed, uncommitted, and untracked changed paths.

Results are `in-sync`, `drift-detected`, `review-required`, or `anchor-unavailable`.
Planning-relevant paths require developer review; `drift-check` never rewrites planning
documents, source files, Git state, or the anchor. After review, the separate explicit
`drift-acknowledge` command refreshes only the local safe anchor; normal reconciliation
continues through the preview-and-approval workflow.

## Safety boundaries

- Static inspection does not run installs, package scripts, migrations, services,
  containers, deployments, or external-system operations.
- RepoCharter does not upload repository content or collect telemetry.
- Candidate commands are evidence, not execution results.
- `observedChecks` records only separately approved executed checks or explicit skips;
  skipped checks are never reported as passed.
- A documented native adapter remains `unverified` until its fresh-agent behavior
  evaluation is recorded.

For generated-file ownership and recovery, read [generated-files.md](./generated-files.md).
For current native instruction-surface evidence, read
[agent-instruction-surfaces.md](./research/agent-instruction-surfaces.md).