stack/docs/plans/2026-09-16_discord-git-tools.md

# Discord Sage: git for the strategy repository (#1509, QUEUE row 24)

Jason's word, 2026-09-16, after the first write from Discord landed:
"Sage will need to have git tooling to commit, push, pull, etc. for the
shared-signals repo." This replaces the row 23 rule that Jason commits
from the terminal.

## 1. Outcome

A decision reached in Discord ends up committed and pushed to
`shared-signals` on GitHub, by Sage, in the same conversation, with the
commit and push in the turn record. Sage still has no shell and no git
anywhere else.

## 2. What is built

Four fixed verbs in the extension, each a `git` child process with a
fixed argument list, run only in a root that is marked `"write": true`
and is a git work tree. No verb takes free-form arguments.

- `git_status(root)`: branch, ahead/behind, changed paths. Read only.
- `git_commit(root, message, paths)`: stages exactly the named paths
  (one to fifty; the "every change when omitted" form of the first draft
  was dropped for section 6's explicit-path rule, since the root is
  Jason's own clone), refuses a dot-prefixed path or a
  path outside the root, refuses when the index already holds staged work, refuses an empty message or one over 500
  characters, refuses when nothing is staged, commits with author
  `Sage <[email protected]>` and a trailer naming the Discord author
  by role (`Requested-by: Jason` or `Carmen`, never an id). Returns the
  short hash.
- `git_pull(root)`: `git pull --ff-only origin <current branch>`. A
  non-fast-forward result is refused with the reason and nothing is
  merged or rebased.
- `git_push(root)`: `git push origin <current branch>`, current branch
  only, never `--force`, never a tag, never another remote.

Fences shared by all four: the root's work tree must be clean of
conflicts and not mid-merge or mid-rebase; the current branch must be
the one the binding names (`"branch": "main"`), so a detached head or
another branch refuses; 60 s timeout; stdout and stderr are captured,
trimmed to 4 KiB and returned as data; exit codes become fixed refusals.

Credentials, as built (2026-09-18; the draft above said the fleet helper
would serve): `~/.mosaic/tools/git/git-credential-mosaic` answers only
the two Gitea hosts and exits silently for github.com, and the host's
global git config sends github.com to Jason's own `gh` login. Neither is
acceptable for Sage, so the verbs run git with `GIT_CONFIG_GLOBAL=/dev/null`,
`GIT_CONFIG_NOSYSTEM=1`, no askpass, no prompt, and one helper set
through `GIT_CONFIG_COUNT`: the package's `bin/git-credential.mjs`,
which answers `get` over https from the 0600 file the binding names in
`tokenFile`. The connector checks the file's mode at load and never reads
it; the path reaches git only for push, pull and reserve, through the
environment, never as an argument. The token is never read by the
connector, printed, journaled or passed as an argument; a push failure
returns git's message with any `https://…@` form and token shape masked.
The D5 identity (seat token, `Sage <[email protected]>`) is unchanged;
only the mechanism that presents it differs from the draft.

The requester in the trailer is the Discord author's server name, which
the connector now writes into the envelope line (`requester="…"`) and the
extension reads on `before_agent_start`. A turn without a requester
cannot commit.

Binding (`tools` key, fixed), as built:

```json
{ "name": "shared-signals", "path": "…/shared-signals", "write": true,
  "git": { "branch": "main", "identity": "sage",
           "tokenFile": "…/secrets/github-jetrich-sage.token",
           "author": "Sage <[email protected]>", "protocol": "vault" } }
```

Without `git` on a root, no git verbs are offered for it. The prompt
paragraph says which root has git, that a commit is real once pushed,
and that Sage reports the hash.

## 3. Not built

No shell, no arbitrary git arguments, no branches, no force, no tags, no
other remotes, no rebase, no reset, no history rewriting, no git in the
Mosaic roots. A pull that needs a merge stops and says so; Jason resolves
it from the terminal.

## 4. Evidence

- `packages/discord/tests/git.test.mjs` against a local bare remote:
  status, commit with the trailer, pull ff-only, push; refusals for an
  empty message, a dot path, a path outside the root, a non-ff pull, a
  detached head, another branch, a conflicted tree; no token in any
  argument list or output.
- Suite: the extension exposes the four verbs only with a `git` key.
- Live: Jason asks in #ideas for a decision to be written, committed
  and pushed; the GitHub commit shows Sage as author and the trailer;
  the turn record shows write, commit and push.

## 5. Rulings from Jason (2026-09-16, evening)

- D5. Identity: the sage seat's GitHub token (`github-jetrich-sage`
  in the seat's secrets, resolved by the existing helper), author
  `Sage <[email protected]>`. Ruled: "That email works is acceptable."
- D6. Push every time. Ruled against the recommendation to push only on
  request: "This will be fatal. Failure to automatically push will result
  in stale data." So every commit pushes at once; a commit whose push
  fails is reported as such in the reply and the turn record, and the
  next commit retries the push.
- D7. Reviewer: rev-code-02 on #1509. Ruled: "agree".

## 6. Shared-signals record protocol (briefed 2026-09-17 by shared-signals-05)

Verified against `origin/main` of `jetrich/shared-signals` (tooling landed in `8f0d946`; main at `7aa88ad` on 2026-09-17):
`tools/vault_lock.py`, `tools/validate_vault.py`, `docs/ID-REGISTRY.txt`,
`docs/RECORDS.md` "Reserving IDs and locking files", AGENTS.md step 4.
A record's id must be reserved in the registry before the file exists,
the registry is append-only and committed, `validate_vault.py` fails a
commit whose ids are not registered or are used twice, and a file being
edited for more than a moment is locked per clone under `.vault-locks/`
(gitignored, fcntl, default TTL 3600 s). Owner comes from
`VAULT_LOCK_OWNER`, then `MOSAIC_AGENT_NAME`, then git user.name; the
connector already sets `MOSAIC_AGENT_NAME` to the seat, so locks read
"sage" with no change.

What this means for the verbs, since Sage never gets a shell:

- `git_commit` runs `python3 tools/validate_vault.py` in the root first
  and refuses the commit, with the validator's first lines, when it fails.
  It also runs `vault_lock.py check` on the staged paths and refuses when
  another owner holds one.
- A new fixed tool `reserve_id` (prefix BUS, PRJ, SS, DEC or REF plus a
  title) runs `vault_lock.py reserve` and returns the id; the registry line
  it appends is staged with the record in the next commit. `write_file` of
  a new record without a reserved id is not blocked by the connector; the
  validator catches it at commit, and the prompt tells Sage to reserve
  first.
- `write_file` and `edit_file` take the clone lock for the path around the
  write (`lock`, write, `unlock`), so a terminal contributor on the same
  clone sees the claim. A live lock held by another owner refuses the write
  with that owner's name in the reply.
- Staging is by explicit path only: Sage's changed records plus the
  registry. Jason's own uncommitted files in the same clone (the write root
  is his clone) are never swept in. `git_pull` is ff-only and refuses when
  the paths it would touch are dirty.
- Push after every commit (D6). A push that fails is said in the reply and
  retried by the next commit.

These scripts are Python in the shared-signals repo, not Mosaic code; the
connector calls them as fixed argv, never through a shell, and only inside
the root marked writable.

## 7. Order

After row 23's web tools are reviewed. Git verbs, tests, suite, review,
local commit, then the binding change and a live check.