From 47327d90d87d434c1fd9637f8d6e410f2b030c28 Mon Sep 17 00:00:00 2001 From: Ty Date: Mon, 27 Jul 2026 10:04:19 -0700 Subject: [PATCH] Require Git hygiene for all agents in this workspace. Bind commit/push/PR safety, gitea_vps-only remote ops, and secret scans in AGENTS.md, with CLAUDE.md and Grok rules so every harness loads them. --- .gitignore | 34 ++++++++++++++ .grok/rules/git-hygiene.md | 17 +++++++ AGENTS.md | 93 +++++++++++++++++++++++++++++++++++++- CLAUDE.md | 13 ++++++ CONTRIBUTING.md | 56 +++++++++++++++++++++-- README.md | 1 + SECURITY.md | 1 + 7 files changed, 209 insertions(+), 6 deletions(-) create mode 100644 .grok/rules/git-hygiene.md create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 8acda7e..34a77e5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,45 @@ +# Secrets and local env (never commit) .env .env.* !.env.example +*.pem +*.key +id_rsa* +id_ed25519* +credentials.json +token.json +secrets/ +**/secrets/ + +# Runtime / local state state/ *.log +logs/ + +# Python .venv/ +venv/ __pycache__/ +*.py[cod] .pytest_cache/ .ruff_cache/ .mypy_cache/ +.coverage +htmlcov/ +dist/ +build/ +*.egg-info/ + +# Node (if introduced later) +node_modules/ + +# OS / editor noise .DS_Store +Thumbs.db +*.swp +*~ + +# Agent / IDE local overrides (do not commit personal agent state) +CLAUDE.local.md +.claude/settings.local.json +.grok/local/ diff --git a/.grok/rules/git-hygiene.md b/.grok/rules/git-hygiene.md new file mode 100644 index 0000000..e2b4822 --- /dev/null +++ b/.grok/rules/git-hygiene.md @@ -0,0 +1,17 @@ +# Git hygiene (Salon_Assistant) + +Mandatory. Full rules: repository root `AGENTS.md` → section **Git hygiene (mandatory)**. + +Quick binding rules: + +- **gitea_vps only** for this product’s remote Git/PR MCP (`Ty_Tech/Salon_Assistant`). Never `gitea_mcp_for_ty` or localhost Git MCP. +- **No secrets** in commits, messages, PRs, or issues. +- **No `git config`** changes. +- **No force-push to `main`**, no `--no-verify`, no amend of published commits unless the user explicitly orders it. +- **Commit / push / open-or-merge PR only when the user asks.** +- Before commit: `status` + staged diff; stage explicit paths only; scan for credentials. +- Feature work on named branches (`docs/`, `design/`, `chore/`, `fix/`, `feat/`); base PRs on `main`. +- Confirm before destructive Git (hard reset, clean -fd, remote branch delete, history rewrite). +- Subagents inherit these rules. + +Detail and checklists: `AGENTS.md`, `CONTRIBUTING.md`, `SECURITY.md`. diff --git a/AGENTS.md b/AGENTS.md index e852f13..cf389c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,9 @@ Remote: Gitea **Ty_Tech/Salon_Assistant** (via **gitea_vps** MCP only for this p 2. [`design/use-cases.md`](design/use-cases.md) 3. [`design/scenarios.md`](design/scenarios.md) 4. [`design/DECISIONS.md`](design/DECISIONS.md) -5. [`docs/README.md`](docs/README.md) (operator manuals) +5. [`docs/README.md`](docs/README.md) (operator manuals) +6. **This file’s [Git hygiene](#git-hygiene-mandatory)** — binding for every agent session +7. [`CONTRIBUTING.md`](CONTRIBUTING.md) for PR/branch detail ## Hard rules @@ -20,10 +22,97 @@ Remote: Gitea **Ty_Tech/Salon_Assistant** (via **gitea_vps** MCP only for this p - **No** `gitea_mcp_for_ty` / localhost Git MCP for this product — **gitea_vps** only. - Owner never gets terminal/nano/docker instructions. - No agent pay; no silent send/publish. -- **`design/`** = product POR SSOT; **`docs/`** = operator runbooks. +- **`design/`** = product POR SSOT; **`docs/`** = operator runbooks. +- **Git hygiene below is mandatory** for every agent (Grok, Claude, Cursor, subagents, scripts). ## Git MCP - Server: `gitea_vps` - URL: `https://giteamcp1.vps1.afterthedemo.com/mcp` - User-Agent: `grok-connectors-manager/` +- Repo: **owner `Ty_Tech`**, **repo `Salon_Assistant`**, default branch **`main`** + +--- + +## Git hygiene (mandatory) + +Every agent that opens or works in this workspace **must** follow these practices. Deeper dirs inherit this file; do not weaken these rules in subdirectory `AGENTS.md` files. + +### Identity of the remote + +| Item | Value | +|------|--------| +| Hosted remote | Gitea `Ty_Tech/Salon_Assistant` | +| Default branch | `main` | +| Agent Git / PR MCP | **`gitea_vps` only** | +| Forbidden | `gitea_mcp_for_ty`, localhost Git MCP, inventing a second product remote | + +Prefer local `git` for status/diff/commit/branch on the workspace clone; use **`gitea_vps`** for remote PR/branch/file ops against the product repo when MCP is appropriate. Never mix this product’s Git ops onto another MCP server. + +### Never (unless the user explicitly orders that exact action) + +| Action | Why | +|--------|-----| +| `git config` (any scope) | Do not change user or repo identity/settings | +| Commit or push **secrets** | `.env`, tokens, keys, OAuth dumps, provider credentials, PII exports | +| Force-push to `main` (or rewrite its history) | Shared default branch is protected by practice | +| `--force` / `--force-with-lease` push without explicit ask | Easy to destroy remote work | +| `--no-verify` / skip hooks | Hooks exist to catch mistakes | +| Amend a commit already pushed | Rewrites shared history | +| `reset --hard`, `clean -fd`, branch delete on remote | Destructive; confirm first | +| Push, open/merge PR, or tag release without user request | Shared/remote side effects need intent | +| Commit unrelated dirty files “while you’re at it” | Keeps history reviewable | +| Commit build artifacts, caches, venvs, logs, local IDE noise | Belongs in `.gitignore` | +| Paste secrets into commit messages, PR bodies, or issues | Transcripts and remotes leak | + +### Always + +1. **Orient before mutating Git:** `git status`, `git diff` / `git diff --staged`, and recent `git log` (e.g. `git log -5 --oneline`) so commits match repo style. +2. **Work on a branch** for anything beyond a trivial single-commit fix the user asked to land on `main`. Prefer names: + - `docs/…`, `design/…`, `chore/…`, `fix/…`, `feat/…` + - Base new branches on up-to-date `main` when practical. +3. **Stage only intended paths** (`git add `). Never `git add -A` / `git add .` without reviewing the full set. +4. **Scan the staged diff for secrets** before every commit (`.env*`, keys, tokens, cookies, private URLs with credentials). +5. **Commit only when the user asks** to commit/save/checkpoint (or an explicit workflow that includes commit). +6. **Commit messages:** concise focus line in imperative mood; 1–3 sentences of *why* when non-obvious. Match existing history tone. No secret data. No noisy AI trailer spam unless the user asks for a trailer. +7. **Push only when the user asks.** Prefer upstream tracking (`-u`) on first push of a branch. +8. **PRs via `gitea_vps`:** base `main`, clear title/body (summary + test plan / how verified), draft/WIP when incomplete. Do not merge unless asked. +9. **Confirm before destructive or shared-visible actions:** force-push, hard reset, remote branch delete, PR merge/close, rewriting published commits, mass file deletes. +10. **Leave the tree honest:** do not hide failures by amending away broken intermediate state the user still needs; do not discard uncommitted user work. +11. **Respect “no build”:** do not commit product implementation until **build** / **implement** is authorized; docs/design/scaffold hygiene changes are fine when requested. +12. **Subagents inherit these rules.** When spawning agents, point them at this file or restate: no secrets, no force to `main`, no push/PR/merge without user ask, `gitea_vps` only for product remote Git MCP. + +### Commit checklist (before `git commit`) + +```text +[ ] User asked to commit (or workflow explicitly includes commit) +[ ] Branch is correct (not accidental detached HEAD / wrong fork) +[ ] git status + staged diff reviewed; only intended files staged +[ ] No secrets, credentials, owner PII, or local absolute machine dumps +[ ] No caches/venv/logs/state that should be gitignored +[ ] Message explains purpose; matches repo style +[ ] Hooks will run (do not pass --no-verify) +``` + +### Push / PR checklist + +```text +[ ] User asked to push and/or open PR +[ ] Branch name is descriptive +[ ] Remote is origin → Ty_Tech/Salon_Assistant (Gitea) +[ ] PR uses gitea_vps; base = main +[ ] Description states what/why and how checked +[ ] No secrets in PR text or screenshots paths +``` + +### Recovering from mistakes + +- Unstaged junk → restore files carefully; never `clean -fd` without listing what will die and getting confirmation. +- Bad unpushed commit → amend only if HEAD is yours, not pushed, and user wants amend; otherwise new commit or interactive fix with consent. +- Secret committed → **stop**; do not keep pushing. Tell the user; rotate credentials; remove from history only with explicit coordinated procedure (not casual `push --force` to `main`). + +### Related docs + +- Branch/PR conventions: [`CONTRIBUTING.md`](CONTRIBUTING.md) +- Security / no secrets in git: [`SECURITY.md`](SECURITY.md) +- Ignore patterns: [`.gitignore`](.gitignore) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d014b3f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,13 @@ +# Claude / coding-agent instructions — Salon_Assistant + +This directory is the **Salon_Assistant / Lumina** product seed (Gitea `Ty_Tech/Salon_Assistant`). + +1. Read and follow **[AGENTS.md](AGENTS.md)** in full — product hard rules **and mandatory Git hygiene**. +2. Design SSOT: `design/DESIGN_PLAN.md`, `design/use-cases.md`, `design/scenarios.md`, `design/DECISIONS.md`. +3. Operator docs live under `docs/`; do not treat them as a second design SSOT. +4. **No product implementation** until the user says **build** / **implement**. +5. Git remote ops for this product: **`gitea_vps` only** — never `gitea_mcp_for_ty` or localhost Git MCP. +6. Platform-first: `nemohermes` / `openshell` only; no parallel control API. +7. Owner-facing answers must never include terminal, nano, or Docker instructions. + +If any instruction conflicts, **this tree’s `AGENTS.md` wins** over parent workspace notes for product work inside `Salon_Assistant/`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68c9983..87badcd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,7 @@ 1. Read [design/DESIGN_PLAN.md](design/DESIGN_PLAN.md). 2. Read [design/use-cases.md](design/use-cases.md), [design/scenarios.md](design/scenarios.md), [design/DECISIONS.md](design/DECISIONS.md). 3. Implementation requires an explicit **build** decision for greenfield features; structural and documentation work follows this CONTRIBUTING guide. +4. Coding agents must also follow **[AGENTS.md](AGENTS.md)** — especially **Git hygiene (mandatory)**. ## Platform-first @@ -13,15 +14,51 @@ ## Git ops for this product -- Remote: Gitea **Ty_Tech/Salon_Assistant**. -- Agent Git MCP for this product: **gitea_vps** only (`https://giteamcp1.vps1.afterthedemo.com/mcp`, User-Agent `grok-connectors-manager/`). +| Item | Value | +|------|--------| +| Remote | Gitea **Ty_Tech/Salon_Assistant** | +| Default branch | `main` | +| Agent Git MCP | **`gitea_vps` only** (`https://giteamcp1.vps1.afterthedemo.com/mcp`, User-Agent `grok-connectors-manager/`) | +| Forbidden MCP | `gitea_mcp_for_ty`, localhost Git MCP for this product | + +Local `git` on a clone is fine for day-to-day status/diff/commit. Use **gitea_vps** for remote PR/branch operations against the product repo when working as an agent with MCP. + +## Branching + +- Branch from current `main`. +- Prefer prefixes: `docs/`, `design/`, `chore/`, `fix/`, `feat/`. +- Keep branches focused; one concern per branch when practical. +- Do not force-push `main`. Do not rewrite published history without explicit coordination. + +## Commits + +- **No secrets** in trees or messages (see [SECURITY.md](SECURITY.md) and `.gitignore`). +- Stage only files that belong to the change; review `git status` and the staged diff. +- Prefer small, reviewable commits with imperative subject lines and a short *why* when needed. +- Do not skip hooks (`--no-verify`) unless an operator explicitly requires it for a broken-hook emergency. +- Agents: commit/push only when the user asks (see AGENTS.md checklists). ## Pull requests -- Branch from `main`. +- Base: `main`. +- Title reflects the change; body includes summary and how it was verified. - Keep use-case SSOT in `design/use-cases.md` (do not duplicate full matrices in README). - Run `make verify` when implementation exists (fixture CI). -- No secrets in commits. +- Agents open/update PRs via **gitea_vps**; merge only when the user asks. +- No secrets, tokens, or production PII in PR text. + +### Suggested PR body shape + +```markdown +## Summary +- … + +## Verification +- [ ] … (e.g. docs-only review / make verify / doctor) + +## Notes +- Related design decisions / use cases if any +``` ## Code style @@ -33,3 +70,14 @@ - Tag releases (`vX.Y.Z`). - Pin images and MCP package versions in the release manifest. - `scripts/upgrade.sh` is the operator upgrade entrypoint (see docs/UPGRADE.md). +- Changelog: [CHANGELOG.md](CHANGELOG.md) (Keep a Changelog). + +## Hygiene anti-patterns + +| Avoid | Prefer | +|-------|--------| +| Commit `.env`, keys, OAuth dumps | OpenShell providers / host env; examples only as `.env.example` | +| `git add .` without review | Explicit paths after `git status` / diff | +| Drive-by refactors in unrelated PRs | Separate branch/PR | +| Force-push to shared `main` | Revert commit or forward fix | +| Agent “cleanup” that deletes unknown user files | Investigate; ask before destructive clean | diff --git a/README.md b/README.md index 4866a2e..0c81780 100644 --- a/README.md +++ b/README.md @@ -45,3 +45,4 @@ Code under `skills/`, `scripts/`, `services/`, `policy/`, etc. is **scaffold onl - Gitea: `Ty_Tech/Salon_Assistant` (public) - Git MCP for this product: **`gitea_vps`** only +- **Agents:** mandatory Git hygiene is in [`AGENTS.md`](AGENTS.md) (also loaded via `CLAUDE.md` and `.grok/rules/git-hygiene.md`). See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branch/PR conventions. diff --git a/SECURITY.md b/SECURITY.md index 2490bb3..cedcaae 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -5,6 +5,7 @@ - Agent never executes payments, refunds, or bill-pay. - Client outbound messages and social posts are draft-only unless a future gated send is explicitly designed. - Secrets never commit to git (use OpenShell providers / host env). +- Agents: follow **Git hygiene** in [AGENTS.md](AGENTS.md) (secret scan before every commit; never put credentials in messages/PRs). - Owner never receives host shell, Docker, or editor instructions from the assistant. ## Reporting