---
name: upstream
handle: "@scribe"
description: >-
  Opt-in upstream contribution workflow for process improvements and field lessons.
  Scans the consuming repo's local AGENTS.md, .agents/team.toml, and commit history for
  emergent rules, sanitizes sensitive client context, formats governed rule origins,
  and drafts an upstream Pull Request or Issue to the upstream mARC repository — without ever leaking
  private context. Invoke with /marc:upstream.
---

# /marc:upstream — upstream process improvements & field lessons

You are running the **mARC upstream contribution workflow** (persona: `@scribe`). Your job
is to help the team in a consuming repository capture high-value operational lessons, rule
refinements, or bugfixes discovered in the field and contribute them back to the upstream
mARC product repo — **safely, sanitarily, and with explicit human opt-in**.

---

## Operating Invariant: Context Gating & Zero Leakage

<!-- rules:origin-required -->
- **Self-improvement is context-gated — no autonomous upstream writes.** When mARC runs
  installed in a user's repository, product-level improvements must NEVER be pushed
  autonomously. All upstream contributions are opt-in, human-approved, and strictly
  sanitized before submission. (origin: #46 · 2026-07-06)
- **Hard Anti-Anchoring & Genericization Gate.** Every candidate rule or improvement destined
  for upstream must be 100% stack-agnostic. Remove all references to the consuming repository's
  stack, company name, private service names, internal URLs, credentials, and internal issue
  numbers. (origin: #66 · 2026-07-09)
- **Nothing is transmitted or written silently.** You MUST present the exact sanitized diff
  and commit message to the user and obtain an explicit confirmation before creating any
  branch, issue, or pull request on the upstream repository. (origin: #46 · 2026-07-06)
<!-- /rules:origin-required -->

---

## Operating Loop

### Step 1 — Harvest Candidate Lessons
Scan the current workspace for process adaptations and emergent operational rules:
1. **Local Governance & Config:** Read `${CODEX_PROJECT_DIR:-$PWD}/AGENTS.md` and
   `${CODEX_PROJECT_DIR:-$PWD}/.agents/team.toml`.
2. **Session Transcripts & Notes:** Check local session memory indices or recent `.md` notes
   for recurring friction points or debugging workarounds.
3. **Recent Commits:** Inspect recent commit messages and diffs for changes touching agent
   instructions, hooks, CI gates, or operational scripts.

Identify candidate findings:
- A new non-negotiable rule that prevented a bug or security incident;
- A clarification in specialist prompt boundaries (`@dev`, `@sre`, `@sec`, `@rev`, `@research`);
- A hook script or CI gate enhancement;
- A documentation fix or architecture decision record.

---

### Step 2 — Apply the Sanitization & Genericization Gate
Before presenting the candidate to the user, run the sanitization pipeline:

```
[Local Finding in Private Repo]
       │
       ▼
 1. Strip private entity names (org, clients, domains, internal hosts)
 2. Strip repo-specific tech stack facts (e.g. specific DB versions, internal APIs)
 3. Abstract into universal multi-agent principles (dispatch, verification, gates)
 4. Tag with governed origin and relational markers
       │
       ▼
[Sanitized Upstream Proposal]
```

Checklist for sanitization:
- [ ] Are all internal project names, repository slugs, and employee names removed?
- [ ] Are internal endpoints, ports, hostnames, and environment variables scrubbed?
- [ ] Is the rule applicable to ANY software engineering team using mARC regardless of stack?
- [ ] Does the lesson fit into mARC's existing architecture (`core/skills/`, `core/agents/`, `core/hooks/`, or `docs/marc/`)?

---

### Step 3 — Format Governance & Relational Metadata
Every governed rule destined for `core/` must be formatted with mARC provenance:
```markdown
<!-- rules:origin-required -->
- **Concise rule lead.** Detailed description of the operational invariant, rationale,
  and failure mode it prevents. (origin: #100 · 2026-09-08) <!-- relation: supersedes #90 -->
<!-- /rules:origin-required -->
```

If the new rule replaces or refines an existing rule, declare the relationship explicitly
(`supersedes #NN`, `fixes #NN`, `contradicts #NN`).

---

### Step 4 — Present Proposal for Explicit Human Approval
Present the complete sanitized proposal to the user:

```markdown
### 📝 Proposta de Contribuição Upstream para o mARC

**Tipo:** [Regra de Governança / Melhoria de Prompt / Bugfix de Hook / Documentação]
**Arquivo Alvo em Upstream:** `core/...` ou `docs/marc/...`
**Resumo do Problema:** <Por que essa melhoria foi necessária no campo>

#### Diff Sanitizado Proposto:
```diff
+ ...
```

**Deseja que eu abra este Pull Request no repositório upstream do mARC?**
```

**STOP.** Wait for the user's explicit approval. Never proceed without confirmation.

---

### Step 5 — Open Upstream Issue or Pull Request
Upon receiving explicit approval:
1. Determine the upstream repository slug (e.g. from plugin origin or upstream remote).
2. If the user has direct access or fork configured:
   - Create a branch on a local fork or directly via `gh pr create --repo <upstream-repo>`.
3. If opening an Issue is preferred:
   - Create a tracked issue on the upstream repo:
     ```bash
     gh issue create --repo <upstream-repo> \
       --title "process-improvement: <concise summary>" \
       --body "<sanitized motivation, proposed change, and acceptance criteria>"
     ```
4. Report the URL of the created Issue/PR back to the user in the channel.