Git Ops

On first invocation, read `references/orchestrator.md` and follow its welcome protocol.

Move code from Claude's workspace to a git repository with proper branch management, commit structure, and PR descriptions. This is the bridge between "Claude built it" and "it's in version control."

/oc-git — Command Reference

When the user types /oc-git, display this menu:

GIT OPS COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  WORKFLOW
  /oc-commit           Stage + commit with structured message
  /oc-pr               Generate PR description from commits/checkpoint
  /oc-push             Push branch to remote
  /oc-git-sync         Full workflow: branch (from convention) → commit → push → PR
  /oc-merge <pr>       Merge a reviewed PR: checks green, head pinned, the repo's merge method
  /oc-git-release      Tag a merged release + push the tag (closes the ledger)

  UTILITIES
  /checkpoint          Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-git to see this again.

Plain requests, not slash commands: "set up the repo" (clone and prepare the workspace, Phase 0), "git status" (branch, staged changes, remote state and diff since the last commit), and "show / set the git conventions" (branch and commit naming).

How This Skill Works

CLAUDE WORKSPACE                    GIT REPO
<workspace>/project/                github.com/user/project
                                    
  Built files          ──────►      Feature branch
  + checkpoint data    ──────►      Structured commits
  + audit report       ──────►      PR description

The typical flow:

1. Clone the user's repo (or confirm it's already cloned)
2. Create a feature branch following project conventions
3. Copy/move built files into the repo working tree
4. Stage each intended commit and run oc-bug-check; an enrolled Git hook verifies

the exact staged candidate and its immutable PASS receipt at each commit

1. Make structured commits (one per logical unit)
2. Push the branch
3. Run the pre-PR gate: oc-docs-forge (PR docs packet) → oc-repo-ops (readiness

check); docs edits the packet makes are committed (through the bug-check gate) and pushed before the readiness check

1. Generate a PR description from the checkpoint + commit log + docs packet

Phase 0: Repository Setup ("set up the repo")

First Time

# Clone the repo
git clone <repo-url> <workspace>/<project-name>
cd <workspace>/<project-name>

# Verify remote
git remote -v

# Check default branch
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'

Returning (repo already cloned)

cd <workspace>/<project-name>
git fetch origin
git checkout main && git pull origin main

Authentication

Git operations require auth. Check in this order:

1. SSH key — ls ~/.ssh/id_* (preferred for push)
2. Git credential helper — git config credential.helper
3. GitHub token — check env GITHUB_TOKEN or GH_TOKEN
4. Ask the user — "I need git push access. Can you provide a GitHub token

or set up SSH?"

Store auth method in the checkpoint so future sessions don't re-ask.

Branch Naming Convention

Default Convention

<type>/<short-description>

Types:
  feat/     New feature
  fix/      Bug fix
  refactor/ Code restructure (no behavior change)
  chore/    Dependencies, config, tooling
  docs/     Documentation only
  test/     Test additions or fixes
  deploy/   Deployment-related changes

Examples:

• feat/storefront-checkout-module
• fix/auth-session-expiry
• chore/update-wrangler-config
• deploy/add-staging-workflow

Convention from Checkpoint

If an oc-app-architect checkpoint exists, derive the branch name from it:

• Sprint 1 build → feat/sprint-1-auth-flow
• Code audit fix → fix/audit-f001-rate-limiting
• Deploy setup → deploy/ci-cd-pipeline

Naming conventions ("show / set the git conventions")

Set or view the project's naming conventions:

# Store in project config
cat > .git-ops-config.json << 'EOF'
{
  "branch_prefix": "feat|fix|refactor|chore|docs|test|deploy",
  "commit_format": "conventional",
  "default_base": "main",
  "pr_template": true,
  "auto_lint_before_commit": true
}
EOF

Commit Structure (/oc-commit)

Conventional Commits

<type>(<scope>): <description>

[optional body]

[optional footer]

Commit Granularity

One commit per logical unit of work. Rules of thumb:

Auto-Commit from oc-app-architect Phase 6 Sprints

When oc-app-architect completes a Phase 6 sprint, oc-git-ops can auto-structure commits:

# Read the sprint contract for commit scoping
# Each contract deliverable becomes one commit
# Invoke /oc-bugcheck run for each staged group before committing;
# the enrolled Git hook verifies each exact candidate at the commit boundary.

# Example for Sprint 1: Auth
git add src/db/migrations/ src/db/schema.ts
git commit -m "feat(db): add users and sessions tables"

git add src/auth/ src/middleware/session.ts
git commit -m "feat(auth): implement WebAuthn passkey flow"

git add src/auth/__tests__/ tests/
git commit -m "test(auth): add unit + integration tests for passkey auth"

Pre-Commit Gate (auto-invokes oc-bug-check)

Enrollment precondition. /oc-commit refuses to commit in a repository that is not enrolled (no installed verifier beneath the Git common directory — git rev-parse --git-common-dir has no opchain/ runtime and no opchain pre-commit hook). Say so in one line — "repo not enrolled — run /oc-enroll first" — and stop; do not fall back to reasoning over test output as the gate. Enrollment is a one-time step per clone.

Stage the intended commit, then invoke oc-bug-check before `git commit`. This is the canonical pre-commit workflow — oc-git-ops does NOT run its own ad-hoc lint/type/test checks. Bug-check owns the seven-check suite (types, lint, tests, anti-patterns, secrets, build, deps) and decides PASS or FAIL.

Skill(skill="oc-bug-check", args="/oc-bugcheck run")

Read the bug-check result and .checkpoints/oc-bug-check.checkpoint.json for diagnostics and last-run history. The checkpoint does not authorize a commit. At the Git boundary, the enrolled hook verifies the immutable staged candidate and revalidates a matching PASS receipt beneath the Git common directory (oc-bug-check § Commit gate contract).

Mechanical commit enforcement requires Git enrollment. From a repository checkout, run node scripts/install-git-drivers.mjs --enroll --repo "$(git rev-parse --show-toplevel)"; packaged plugin users run /oc-enroll. Plugin installation alone does not enroll a repository: its SessionStart/Stop hooks provide state and suggestions, and Claude PreToolUse hooks do not authorize or deny commits.

Enrollment installs the Git pre-commit hook and copies the verifier and receipt library beneath the Git common directory. Later commits use that installed runtime. A foreign hook is preserved; required enrollment returns BLOCKED with the exact final-decision snippet for manual hook-manager integration. Validate the composed hook before claiming enforcement. Repository marker directories alone do not install the hook.

The hook finishes any authoring-repository mirror updates, snapshots the effective index with git write-tree, runs the declared policy checks on that immutable candidate, and writes and revalidates a create-once receipt. The receipt binds repository, candidate tree, policy/config, toolchain, verifier and check results. Missing tools, non-PASS checks, index changes or mismatched evidence block the commit. Each distinct staged group requires its own matching receipt. Local hooks can be deliberately disabled; protected CI must independently verify the received candidate.

PR Description (/oc-pr)

Auto-Generated from Context

Pull from all available sources to build a comprehensive PR description:

1. Commit log — git log main..HEAD --oneline
2. App-architect checkpoint — which roadmap tasks this covers, the Phase 6

sprint contract and evaluator scores

1. Code-auditor checkpoint — findings addressed, remaining issues
2. Docs-forge checkpoint — skill_state.pr_body_fragment (the ## Documentation

section) and pr_comment_marker for the optional docs comment

PR Template

## Summary

[2-3 sentences: what this PR does and why]

**Linked ticket:** [TICKET-1234](ticket-url)

## Changes

[Auto-generated from commit messages, grouped by type]

### Features
- [feat commits]

### Fixes
- [fix commits]

### Other
- [remaining commits]

## Documentation

[Inserted verbatim from the oc-docs-forge checkpoint (`skill_state.pr_body_fragment`).
The oc-repo-ops gate fails closed if this section is missing. If no user-facing docs
changed, oc-docs-forge says so explicitly and explains why — silence is not a pass.]

## Testing

- [ ] Unit tests pass (`npm test`)
- [ ] Type check passes (`tsc --noEmit`)
- [ ] Manual testing completed
[If oc-app-architect Phase 6: "Evaluated by oc-app-architect evaluator: X.X/10 (sprint N)"]

## Audit Status

[If oc-code-auditor ran: "Pre-deploy audit: Grade [X], [N] findings ([M] addressed in this PR)"]
[If not: "No code audit run — consider `/oc-audit pre-deploy` before merging"]
[Pre-PR gate: "oc-docs-forge packet ✓ · oc-repo-ops verdict PASS" — from the gate checkpoints]

## Deployment Notes

[Any migration steps, env var additions, or config changes needed]
[Auto-detected from: new migration files, .env.example changes, wrangler.toml changes]

Refs: TICKET-1234

Pre-PR Gate (binder by default; oc-docs-forge → oc-repo-ops when docs change)

Before creating any PR, bind the pre-PR evidence and verify it — before `git push`. The order is bind → push → PR, so the evidence travels with the branch and no PR opens red on the evidence:pr check (2026-10-08 audit, Q5-F2: 10 of 33 PRs opened with no evidence and were repaired after CI red at 3–10× the proactive cost). oc-git-ops does NOT write its own docs packet or hygiene checks; Docs Forge owns the PR documentation packet and Repo Ops decides whether the repository is clean enough to open the PR.

Default path — the PR changes no reader-facing docs. One deterministic binder writes both tree-bound handoffs; no Skill invocation and no hand-written JSON:

node scripts/checkpoint.mjs handoff oc-docs-forge --policy pr-docs-v1 --verdict PASS --scope "<files the PR touches>" --evidence "<why no README/CHANGELOG/docs/runbook/SKILL.md changed>"
node scripts/checkpoint.mjs handoff oc-repo-ops --policy pr-readiness-v1 --verdict PASS --scope "<same scope>" --evidence "<generated files current; no orphaned artifacts; gitignore policy holds>"
npm run evidence:pr

Commit the checkpoint edits (chore(evidence): bind pre-PR handoffs), then push.

Docs path — the PR changes README, CHANGELOG, `docs/`, runbooks or a SKILL.md. Keep the two Skill invocations; each writes its own handoff and the packet is real work:

Skill(skill="oc-docs-forge", args="/oc-docs pr")

Then read .checkpoints/oc-docs-forge.checkpoint.json and insert skill_state.pr_body_fragment (the ## Documentation section) into the PR body. If pr_comment_marker is set, post the docs comment after the PR opens.

Skill(skill="oc-repo-ops", args="/oc-repo verify")

Either path ends with npm run evidence:pr (node scripts/lib/release-evidence.mjs --stage pr). It requires A's canonical PASS receipt for the exact candidate tree plus C-contract Docs Forge (pr-docs-v1) and Repo Ops (pr-readiness-v1) PASS handoffs bound to the HEAD tree projection excluding .checkpoints/. A squash merge whose source content changes produces a different projection and cannot reuse the prior evidence.

Consumer repositories. The evidence:pr CI check exists in a consumer repo only after node scripts/install-git-drivers.mjs --ci (offered by /oc-enroll) has written the evidence workflow into its .github/workflows/. Until it runs there, no PR check backs this gate and the edge is prose; run it once per repo and treat a red evidence job as a blocker, not a flake.

Required order (from the oc-repo-ops Every-PR Gate): bug-check (already run before every commit, including any docs-packet commit) → docs-forge → repo-ops → PR.

Creating the PR

# If gh CLI is available
gh pr create --title "[type]: [description]" --body-file /tmp/pr-description.md

# If not, output the description for the user to paste
echo "PR description saved to: /tmp/pr-description.md"
echo "Create the PR manually and paste this description."

Full Sync Workflow (/oc-git-sync)

One command that runs the entire flow:

/oc-git-sync [description]

1. Detect context — read checkpoints for project, skill, and current state
2. Determine branch name — from checkpoint or description
3. Create branch — git checkout -b <branch>
4. Stage changes — intelligently stage (skip build artifacts, node_modules)
5. Run oc-bug-check gate — invoke Skill(skill="oc-bug-check", args="/oc-bugcheck run") after the last edit and before any commit. FAIL aborts the sync — surface the failing checks and stop. The user can /oc-bugcheck fix, address the failures and re-run /oc-git-sync, or bypass explicitly as described in the Pre-Commit Gate table.
6. Structure commits — group by logical unit. For each distinct staged group, rerun step 5 before committing; the enrolled Git hook verifies that group's exact candidate and matching receipt. A PASS for one index tree does not cover other groups or later edits.
7. Bind pre-PR evidence (before the push, so the PR never opens red). Code-only change → run the two node scripts/checkpoint.mjs handoff … binder lines from the Pre-PR Gate. Reader-facing docs changed → invoke Skill(skill="oc-docs-forge", args="/oc-docs pr") to produce the ## Documentation body fragment (and any README/product-doc edits that must travel with the change)
8. Commit the docs edits — if step 7 changed files, stage them, re-run the oc-bug-check gate (step 5), commit (docs: …), and re-run /oc-docs pr at most once more so the packet's verified_for_sha is the new HEAD (if that run edits files again, stop and surface it rather than looping). Skip when step 7 changed no files.
9. Run the readiness gate — docs path: invoke Skill(skill="oc-repo-ops", args="/oc-repo verify"); binder path: the pr-readiness-v1 handoff from step 7 stands. Either way, npm run evidence:pr. FAIL aborts the sync before anything is pushed — surface the blocking findings; the user can /oc-repo clean or fix and re-run. Commit the checkpoint edits (chore(evidence): bind pre-PR handoffs).
10. Push — git push -u origin <branch> (bind → push → PR; in a consumer repo the evidence:pr CI job from install-git-drivers --ci re-checks the pushed head)
11. Generate PR description — from all available context, inserting the docs packet's ## Documentation fragment
12. Create PR — via gh CLI or output for manual creation

At each step, show progress. If any step needs user input, ask once and continue.

Post-Sync Handoff

After /oc-git-sync completes successfully, hand off per orchestrator §3 ("git-sync completes"). Deploying is a user decision, so confirm first:

• If an oc-deploy-ops config exists for this project, ask: "Changes pushed. Run

the deploy audit and deploy to staging?" On yes, invoke Skill(skill="oc-deploy-ops", args="/oc-deploy audit"), then Skill(skill="oc-deploy-ops", args="/oc-deploy staging").

• If no oc-deploy-ops config exists, offer /oc-deploy init to set up

deployment, or /oc-audit pre-deploy for a quality check.

Merging a PR (/oc-merge)

/oc-merge <pr>

The step after /oc-git-sync, and the git request people make most often in plain words: "merge", "merge 252", "squash-merge PR 247 pinned to head …", "auto-merge 644 when it's ready". Until 2.1 this skill had no verb for it, so a merge request that reached the skill landed on the /oc-git menu (7 of 11 git-ops routes in the 2026-10-19 → 10-23 router shadow log).

1. Read the PR from GitHub, not from the conversation.

gh pr view <pr> --json number,state,isDraft,mergeStateStatus,headRefOid,baseRefName,statusCheckRollup. A SHA quoted in a message or a checkpoint can be stale; pin the merge to headRefOid exactly as gh returns it, all 40 characters.

1. Refuse what is not ready.

• Draft, closed or already merged: say so and stop.
• A failing required check (evidence:pr included in an enrolled repo): name the

check and stop. Do not merge around it.

• Checks still running: arm auto-merge (step 3 with --auto) instead of waiting in

the session.

1. Merge with the repository's policy. Read it from the repo's CLAUDE.md or

contributing guide; ask once if neither says. The default is:

   gh pr merge <pr> --squash --auto --match-head-commit <headRefOid>

--match-head-commit makes GitHub refuse the merge if anyone pushed after you read the PR.

• Sign-off (DCO) repositories: the squash commit needs the trailer. Pass

--body "<subject>"$'\n\n'"Signed-off-by: <git config user.name> <git config user.email>".

• A human performs the merge (required human review, or a human DCO squash, as

in ainatx/opchain): hand the user the exact command in a fenced block and stop. Do not run it.

• Merge-commit repositories (for example, a staging preview whose deploy checks

ancestry): use --merge, not --squash.

• --admin only when the user says so for this PR, and say in the reply that it

bypassed protection.

1. After it merges. git fetch origin, then fast-forward the main checkout

(git -C <main checkout> pull --ff-only origin main) so hooks and new worktrees run the merged code. Record the merge per Post-Merge Update below, at an inflection point, not per merge.

1. Hand off. A merge to main is the deploy trigger (orchestrator §3, "git-sync

completes"). Ask before invoking oc-deploy-ops; deploying is the user's call.

Release Tagging (/oc-git-release)

oc-release-ops Phase 5 hands off "the merge / tag" to this skill. Until v1.8.3 there was nothing here to catch it: the command reference had no tag verb, so the tag half of that handoff had nowhere to land.

It showed. The 2026-08-26 ledger audit found thirteen shipped releases on /changelog and three tags in git — v1.0 through v1.7 all shipped untagged.

/oc-git-release <semver>

Preconditions

Refuse and explain, rather than tagging anyway, if:

• HEAD is not reachable from origin/main (a release tag on an unmerged branch

is worse than no tag — it points at code nobody else has).

• The project's release version does not equal <semver>. In the opchain.dev

repo that is the lockstep catalog version in skills/*/SKILL.md; in another project it is every version location listed in .opchain/release.yaml (oc-release-ops multi-project mode). A tag that disagrees with the version is a second lie, not a fix.

• (opchain.dev repo only) release-seal.json is missing or names another

catalog version. The seal is the reviewed baseline an eventual tag must inherit.

• A tag v<semver> already exists. Never move a published tag; cut the next

patch instead. In opchain.dev, publish-mcp-registry.yml has already fired for the old one.

Steps

1. git fetch origin main --tags
2. Verify the preconditions above.
3. git tag -s v<semver> -m "release: v<semver> — <theme>" on the reviewed

merge commit. This is a human gate: if the signing key is unavailable, stop rather than substituting an unsigned or agent-authored tag.

1. (opchain.dev repo only) node scripts/check-release-tag.mjs --local —

verify the seal, exact tagged publisher-workflow and server.json payload digests, catalog, ancestry, and tag signature before a push can trigger the OIDC publisher. Elsewhere, git tag -v v<semver> checks the signature.

1. git push origin v<semver> — in opchain.dev this is what triggers

.github/workflows/publish-mcp-registry.yml. An unpushed tag republishes nothing.

1. Record the tag in oc-git-ops.checkpoint.json under

skill_state.release_reconciliation, the shape the v1.9.0 cut wrote:

{ "skill_state": { "release_reconciliation": {
  "release_pr": { "number": 477, "merge_sha": "…", "merged_at": "…" },
  "tag": { "name": "v1.9.0", "object_sha": "…", "peeled_commit": "…",
           "signing_fingerprint": "…", "local_gate": "PASS", "remote_gate": "PASS" }
} } }

1. (opchain.dev repo only) Verify with node scripts/check-release-tag.mjs

(exit 0). This remote gate proves origin contains the same signed tag object, not merely a different tag that peels to the same commit. Elsewhere, git ls-remote --tags origin v<semver> confirms the push.

This verb is not the enforcement

Documenting a verb does not make it run — this file saying so is the same prose that failed for ten releases. The edge is held by scripts/deploy.mjs, which refuses a production deploy when the catalog version has moved somewhere no tag follows. /oc-git-release is what you run to satisfy that guard; the guard is what makes you run it.

Project Governance Awareness

If a GOVERNANCE.md file exists in the project root (generated by oc-app-architect or the project-governance skill), read it before committing. Respect:

• Naming conventions — file naming, branch naming overrides
• Directory structure — where new files should be placed
• Version tracking — which documents are master copies vs. working drafts
• Git strategy — branching model (if different from oc-git-ops defaults)

If governance conventions conflict with oc-git-ops defaults, governance wins — it's project-specific, oc-git-ops defaults are generic.

Checkpoint Integration

The shared checkpoint schema, write rules and resume protocol live in references/checkpoint-protocol.md, bundled with this skill. This section adds only what is specific to oc-git-ops.

Checkpoint Location

{project-dir}/.checkpoints/oc-git-ops.checkpoint.json

When to Write

Post-Merge Update

Restamp merged_prs at sensible inflection points — after a review wave, when a release ships, or when a session ends — not once per merge. Where the project has the checkpoint CLI, the single update is below; otherwise edit .checkpoints/oc-git-ops.checkpoint.json directly (append to skill_state.merged_prs, set step and status, restamp updated_at):

node scripts/checkpoint.mjs update oc-git-ops \
  "--skill_state.merged_prs:json+={...}" \
  "--step=last-merge-#${PR_NUM}" \
  "--status=complete"

Each :json+= flag appends one object; repeat the flag to record several PRs. (Up to v1.9.0 this recipe was written +:json=, which the CLI parsed as a literal key named merged_prs+; the CLI now accepts either order and refuses a key that still carries an operator.) Without the CLI, edit skill_state.merged_prs directly.

Do not automate this per-merge. opchain.dev once ran a .github/workflows/checkpoint-after-merge.yml that opened a bot/checkpoint-stamp-<PR> PR on every merge to main. It was removed 2026-06-22: under branch protection the bot's auto-merge could never satisfy required review, so each merge left a permanent open PR, and because every PR appended to the same merged_prs array they mutually conflicted. The data is reconstructable from git log, so a CI-gated PR per merge is pure cost. See Anti-pattern: don't auto-stamp `merged_prs` per merge in the checkpoint protocol. Other skills' checkpoints (oc-orchestrator, oc-app-architect, oc-ux-engineer, etc.) stay assistant-driven because their content is contextual.

context_primer Template

{
  "key_decisions": [
    "Repo: github.com/acme/acme-core",
    "Auth: SSH key",
    "Convention: conventional commits, feat/fix/chore prefixes",
    "Last push: feat/storefront-module → origin, 6 commits"
  ],
  "generated_files": [
    "pr-description.md"
  ]
}

Cross-Skill Reads

.gitignore Enforcement

When committing, always verify these are gitignored:

node_modules/
.env
.env.local
dist/
build/
.wrangler/
.git-ops-config.json   # Local oc-git-ops config

Do not gitignore .checkpoints/ by default — the checkpoint protocol tracks it in git unless the project's protocol says otherwise, and oc-repo-ops enforces that policy at the pre-PR gate. Only ignore it when the project has explicitly opted out. That includes archived checkpoints: they rotate into the tracked .checkpoints/history/ directory, so there is no .bak pattern to ignore.

If .gitignore is missing entries, add them in a separate chore: update .gitignore commit before the feature commits.

PM-Tool MCP Integration (v1.3+)

When the user invokes any verb with a ticket id — /oc-git-sync TICKET-1234, /oc-commit --ticket PLAT-12, or pastes a Linear / Jira / GitHub Issues URL — oc-git-ops reads the ticket via the configured PM-MCP and uses it for branch, commit, and PR shape.

The runtime contract — concrete tool names, retry policy, idempotency markers, and the pm_deferred_actions[] schema — lives in oc-integrations-engineer/references/pm-mcp-protocol.md, in that skill (not bundled with this skill; install the full catalog, or oc-integrations-engineer alongside it). All MCP calls below honour that contract; this section says only how oc-git-ops shapes branch / commit / PR / state from the ticket.

/oc-git-sync TICKET-1234 flow

1. Resolve provider from .opchain/pm.yaml (or detect from id pattern

/ URL). Apply tool_overrides from pm.yaml before falling through to the registry in protocol §1.

1. Call the registry-resolved get_issue tool (Linear:

mcp__claude_ai_Linear__get_issue; GitHub: mcp__mcp-server-github__issue_read; Jira: mcp__atlassian__jira_get_issue) to fetch title, description, labels, priority, status, assignee. Apply the retry policy from protocol §2.

1. Branch name — slug {type}/{id}-{title-kebab-truncated-50},

where type is derived from the ticket type / labels: feat, fix, chore, docs, refactor. Default feat if ambiguous. The ticket id is mandatory and must preserve the PM tool's canonical casing in the branch name (for example, feat/TICKET-1234-runtime-pm-mcp-made-real or fix/PROJ-57-auth-session-expiry). Do not drop or rewrite the id: Linear / Jira / GitHub integrations auto-link PRs by detecting the ticket id in branch / PR metadata.

1. Commit message — first line: {type}({scope}): {title}.

Body: short paragraph summarising the change; trailer Refs: TICKET-1234 (or Closes: if the ticket is in a "ready-to-close" state).

1. PR title + body — title begins with [TICKET-1234] followed by

the concise change summary. Body is generated from the ticket description, the diff summary, the oc-docs-forge packet (the ## Documentation section), and the auditor / oc-bug-check report (if present). It includes a top-line **Linked ticket:** [TICKET-1234](url) and a plain-text Refs: TICKET-1234 footer so Linear can auto-link even if branch detection fails.

1. PR open — only after the pre-PR gate passes (oc-docs-forge packet

present, oc-repo-ops verdict PASS — see Pre-PR Gate above). Then pre-write check via the list_comments tool (Linear) or issue_read (GitHub, comments inline) for marker <!-- opchain:oc-git-ops:pr-opened:#<pr-number> -->. If absent, call the registry-resolved add_comment tool (Linear: mcp__claude_ai_Linear__save_comment; GitHub: mcp__mcp-server-github__add_issue_comment) with body <!-- opchain:oc-git-ops:pr-opened:#<pr-number> -->\nPR opened: <url>. Then resolve the in_review state string from pm.yaml.states and call the transition tool (Linear / GitHub: save_issue / issue_write with state field; Jira: mcp__atlassian__jira_transition_issue).

1. PR merge (when oc-git-ops observes the merge or is invoked with

/oc-git-sync --closed) — same pre-write check pattern with marker <!-- opchain:oc-git-ops:pr-merged:#<pr-number> -->; comment carries the merge SHA + commit subject; transition to done (resolved from pm.yaml.states).

/oc-commit enrichment

If a ticket id appears in the user's prompt but no /oc-git-sync, just enrich the commit body with Refs: TICKET-1234 and stop — the comment + transition is /oc-git-sync territory. No MCP call is made by /oc-commit alone.

Multi-ticket commits

If the staged diff spans multiple tickets (e.g. user says "this closes PLAT-1 and PLAT-2"), use the first as the branch / PR primary and add a Refs: line per additional ticket. Comment on each via add_comment, each carrying its own ticket-scoped marker <!-- opchain:oc-git-ops:pr-opened:#<pr-number>:<ticket-id> --> so re-runs are idempotent per ticket.

/oc-git-sync --retry-pm flush

Invokes the protocol §4 flush against oc-git-ops.checkpoint.json pm_deferred_actions[]. Filter to skill: "oc-git-ops" and retriable: true. Surfaces flushed N / failed M.

Failure modes

• MCP unavailable / unconfigured → fall back to slug from the user's

prompt and generic commit message; never block the commit on PM-MCP. The PR still opens.

• Ticket id format unrecognised → treat as plain text in the user

prompt; do not call MCP.

• add_comment retry-budget exhausted (transient) → defer per

protocol §4 with retriable: true; user can /oc-git-sync --retry-pm later. The PR is unaffected.

• 403 (cross-team scope) → defer with retriable: false; surface

the permission error; never auto-flush. The PR is unaffected.

Principles

1. One logical change per commit. Not one file per commit. Not one sprint per commit.

The unit is "one thing a reviewer can understand in isolation."

1. Branch names tell a story. feat/sprint-2-crud-api beats update-stuff.
2. PR descriptions are for future-you. Six months from now, this PR title + description

should explain why this change exists without reading the code.

1. Never force-push main. Feature branches can be force-pushed (rebased). Main cannot.
2. Commits are cheap, reverts are cheaper. Small, atomic commits make rollbacks surgical.
3. Auth setup happens once. Store the method in checkpoint, never re-ask.