project — the owner's working repositories beside the vault

Contract

The permissions below govern this procedure; no procedural step may relax them. The load-bearing rules are:

• Explicit instruction only. A passive mention of a repository (an @-mention, a selection, IDEAS.md) never triggers a verb. Every verb that clones, removes or writes into the wiki shows a preview first and waits for the owner's go.
• Placement. New clones go to projects/<name>/ under the configured store (LLM_WIKI_STORE, default ~/.llm-wiki/); an existing working copy outside the vault is registered in place (link --path). A path inside the vault is refused. The sibling store ~/.llm-wiki/repos/ (studied third-party repositories, repo_pack.py clone) is never used here.
• Nothing in a clone is knowledge. The wiki holds the registry row and, per repository, the source page compiled from a snapshot pack in raw/; no page describes a repository from its live tree, no page cites a clone path except the registry.
• No persistent cd. Use git -C <absolute path> … or an absolute file path so commands cannot inherit the wrong directory.
• Credentials never in a URL. Each clone carries a git credential helper that reads its token from credentials.env under the configured store (LLM_WIKI_STORE, default ~/.llm-wiki/); the remote URL is clean (https://git.overleaf.com/<id>, https://github.com/<owner>/<repo>).
• Commits and pushes. Commit on the word commit, or under a standing per-repository policy the owner set on its registry row; the owner is sole author (git config identity, no AI trailer, an imperative one-line message); push on the word push; never a force push, never a rewrite of pushed history, never a branch the instruction did not name. The vault's destructive-git guard (checkout, restore, clean, reset --hard) covers git -C forms too.
• Lanes. A project path reaches a lane only by an explicit grant; git stays the head's instrument; an armed hands-off head needs a pre-flight grant for any project path.
• Logging. link and brief are logged by the ingest they run (the entry's Changed line names the registry row and the pointer); open, sync, commits, pushes, status and unlink change no knowledge and log nothing.

Registry — wiki/tools/Agent Project Store.md

type: tool, the sibling of Agent Repo Store. It carries the rule of use (read or written only under this skill on the owner's instruction; never cited; never read into a compile) and one row per repository:

| name | kind | remotes (role: url) | local path | purpose | project page | channel | commit policy | last sync (date · sha12) | state |

• kind: overleaf (LaTeX on Overleaf) · code · other. channel: overleaf-git (the primary, https://git.overleaf.com/<project-id>) · github-bridge (the fallback, a clone of Overleaf's GitHub mirror; each push then needs the owner's "Pull GitHub changes into Overleaf" click) · github (a plain code repository) · in-place (registered where it is).
• commit policy: on the word commit (default) or the owner's standing sentence for that row.
• state: linked · unlinked (the row stays as the recovery record).
• The row is the single home of the path and the sha; the research-project page in wiki/user/ gets a ## Repository section holding two links only, the registry row and the latest snapshot's source page.

Verbs

link <url> [--name n] [--kind overleaf|code] [--overleaf <project-id>] · link --path <dir> [--name n] [--kind …]

1. Resolve. Name = --name, else the repository's basename (an Overleaf project id alone is not a name: ask). Refuse a name already on the registry; refuse a --path under the vault root; refuse a URL whose user part carries a password (user:secret@host).
2. Channel check (URL only). git ls-remote <clean url> with the helper environment; record the branch list; take the default branch that ls-remote reports. A failure here is reported, never worked around (a missing Overleaf git integration means the github-bridge channel instead).
3. Preview and wait. One table: source · name · destination path (or the registered path) · remotes with roles · channel · commit policy · the brief selection (files and bytes) · what the ingest will log. WAIT for the owner's go.
4. Clone or register. git clone <clean url> <store>/<name> (full history, the remote's default branch); --path: no clone, verify git -C <dir> rev-parse --is-inside-work-tree. Then the credential helper (below) and, for overleaf, a reminder that Overleaf's GitHub-sync feature should be off for that project once direct git is in use.
5. Registry row on the tool page (create the page from the sibling's shape on the first link) and the ## Repository section on the research-project page.
6. Brief (below), then report: the row, the branch, the sha, the snapshot's source page.

open <name>

1. git -C <path> fetch --all --prune.
2. Report first: branch, ahead/behind per remote, modified, staged and untracked files (names), and the porcelain line count (git -C <path> status --porcelain | wc -l) so a "clean" claim carries its number.
3. Pull --ff-only when the tree is clean, else wait for the owner's word; a non-fast-forward is reported with both sides and a merge proposed, never forced.
4. Record the absolute path for the rest of the instruction; every later command names it.

sync <name> [push]

Fetch and pull as in open; report divergence; push only when the instruction says push, then prove it: git -C <path> ls-remote origin <branch> equals git -C <path> rev-parse HEAD. For an overleaf repository, compile first where a TeX engine exists (tectonic <main.tex> in a temporary output directory) and report the result; with no engine, say the build is unchecked.

brief <name>

open (a pull first), then snapshot <name> --brief: the file tree (depth 3), the main document's head (the .tex that holds \documentclass, its first 200 lines), and a README, abstract or outline skeleton where one exists — at most 8 files and 32 KiB (caps set by judgement, unmeasured). A single-file document (one main.tex larger than the per-file cap) has no useful head: its brief is the document itself, packed whole under --allow-large '<why>' with its bibliography, within the 300 KiB safety bound (set by judgement, unmeasured for a new workload).

snapshot <name> [paths…] [--brief]

The only way repository content reaches the wiki.

1. The tree must be clean for the selection (repo_pack.py refuses a modified tracked file or a selected untracked one; the owner commits first).
2. Ledger, then pack, then ingest: python3 .claude/skills/gather/run_ledger.py init --id <project>-<date> --budget 1 python3 .claude/skills/gather/repo_pack.py pack-and-write --repo <absolute path> --paths <p1,p2,…> --slice <sha12> --title "<name> snapshot <date> <sha12>" --rationale "<why these files>" --ledger-id <project>-<date> The pack lands in the raw/ root; /ingest compiles it at standard depth or above. The ingest's de-dup pre-flight matches an existing source page for the same work and updates it as the new version, never a second page; the sort table's authorship rule sends the pack to raw/9-originals/. Confidence high by default (the owner's own work), stamped audited:.
3. Update the registry row's last-sync sha and the project page's source-page link.

status

One table for every row: branch · ahead/behind per remote · porcelain count · sha on disk vs the row's sha · path present and not a symbolic link. Name every row whose path or sha disagrees with disk; propose the fix, apply on the owner's word.

unlink <name>

1. Preview and wait: every branch with unpushed commits (git -C <path> log --branches --not --remotes --oneline), the stash list, untracked files, ahead/behind per remote.
2. On the owner's explicit yes the row's state becomes unlinked and nothing is removed; the reply names the folder at the row's recorded path. Deleting a project folder is a separate act, done only on the owner's explicit ask, which the agent may propose: the agent shows again what the folder holds (unpushed commits, the stash list, untracked files, and any other working tree that depends on it, from git worktree list), and on the owner's yes moves the folder to the system trash (the Bin on macOS), never with rm -rf; a path that is missing or is a symbolic link is reported, not acted on.
3. The project page keeps its links.

The credential helper

Set once per clone, never a token in the URL; the helper reads the key at use time by grep, never by sourcing the file (a cookie value with a ; would execute):

git -C <path> config --local credential.helper ''
git -C <path> config --local --add credential.helper '!f() { echo username=git; echo "password=$(grep "^OVERLEAF_GIT_TOKEN=" "${LLM_WIKI_STORE:-$HOME/.llm-wiki}/credentials.env" | cut -d= -f2-)"; }; f'

The empty first value resets the clone's helper list so a machine-wide helper does not store a second copy. The authorised credential file remains the single home. GitHub remotes use the login gh already holds (gh auth setup-git once per machine if a push prompts). A token that expires or is revoked fails the push with an authentication error: report, stop, no retry loop; the owner renews it in Overleaf's Account Settings and updates the credential file's OVERLEAF_GIT_TOKEN line.

Overleaf specifics

• Endpoint https://git.overleaf.com/<project-id>; username git; the token as the password.
• One branch only, no force push, no branch creation: a branch request on an overleaf row is refused with the reason.
• The GitHub-sync feature and direct git both write the same history; keep one channel per project (the row names it). Under overleaf-git, leaving the sync on is harmless lag until the owner clicks.

Controls (CLAUDE.md §11)

• A "clean tree" claim prints its porcelain count; a "pushed" claim prints the remote sha beside HEAD.
• status reads the registry with a parser over the table rows, never a substring count.
• A refused command (guard, fence, authentication) is reported as the gap it is, never worked around.

Failure handling

Report format

Compact: the verb · the repository (name, branch, sha12) · what changed (files, commit, push proof) · what was written into the wiki (row, source page) · every control with its number. UK English.