Untitled

Anonymous
Plain Text
11/04/2026 11:21 PM
21.6 KB
13
No Index
Never
# GitHub Behavior - Conventions and Procedures

> Entry/loading route: [agents.md](./agents.md). Quality gates: [CoderTeam.md](./CoderTeam.md); lessons learned: [Lessons Learned.md](./Lessons%20Learned.md); model policy: [Token Optimization.md](./Token%20Optimization.md).
> Load A1-A6, B1/B2/B5 at the start of a session; B4 before remote writes/cleanup/agent experiments, other sections when relevant. Project examples in C are not evidence of current state.

# A - Conventions

## A1. Two separate repositories

| Name | Visibility | Purpose |
|---|---|---|
| `<ProjectName>-Intern` | Private | Development/QA with permanent `dev`, `test`, and `main` branches |
| `<ProjectName>-Public` | Public | Description, curated final code and executable releases, independent history |

Use the exact suffixes `-Intern` / `-Public`; `<internal>` and `<public>` below refer to verified `owner/repo` identifiers. Determine the owner/project for each task; names do not replace B2 checks.

**Internal:** working branch -> PR to `dev`; after a complete self-review, `dev -> test` without additional user approval, then invite the user to test. **Move `test -> main` only after the user explicitly approves the specific tested state, every time**; post the QA report before merging. Criteria: CoderTeam 4.

**Public:** separately approved snapshot from internal `main`; curate by file, do not mirror/fork or transfer private branches, commits, issues, or PR contents. Publication under A7 is not authorized by an internal promotion.

## A2. Branches and worktrees

- Never commit directly to permanent branches. Create working branches from current `dev`: `feature/`, `fix/`, `spike/`, `refactor/`, `docs/`, `hotfix/` + a short name. Spikes are short-lived; properly carry over useful results.
- Promote only through PRs `dev -> test -> main`; check the target branch/diff/shared base for independent changes and reversions. Do not silently overwrite.
- **Never delete permanent branches.** Use `gh pr merge --delete-branch` only for temporary working branches, never for `dev`/`test` as promotion sources. Afterwards verify `dev`, `test`, and `main`.
- Internal worktrees share Git history/remotes; Public gets its own clone/staging area without private remotes or historical branches. Folder names do not prove repository identity.
- When renaming a repository, update fetch/push remotes and CI/docs/release references; do not rely on redirects permanently. Worktree folders do not need to be renamed.

## A3. Commits

Conventional Commits: `type: short imperative description`, optionally why and `Refs #N` / `Closes #N`. Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `security`.

Small, coherent commits; no WIP on `main`, secrets/tokens/`.env` files, or build artifacts. Check `.gitignore`. Commits I create end with:

```text
Co-authored-by: Copilot <[email protected]>
```

## A4. Versions and tags

Determine versioning from the current project configuration; `main` adopts exactly the tested version. Release tags: `vMAJOR.MINOR.PATCH`. Cleaning up control files does not change product versioning or release status. BatteryBuddy conventions only appear in C.

## A5. Issues and public triage

- Type: `feature`, `bug`, `security`, `ux`, `performance`, `refactor`, `docs`, `spike`, `question`.
- Priority: `prio:critical|high|medium|low`; status: `status:blocked|in-review|needs-test`; origin: `found-in:test|release` (each is a separate label).
- Feature: goal/value, acceptance criteria, architecture/security/UX perspectives, open questions. Bug: reproduction, expected/actual, platform/app version, severity.
- Every internal project change has a private issue; link the PR. For multiple PRs use `Refs #N`; close the issue only when fully resolved.
- Public bugs/requests in `<public>` require **AI review-group review AND the creator's explicit review/approval before internal adoption**. Check reproducibility, scope, security/privacy; transfer only necessary, sanitized information. Public links may be referenced internally.
- Spam/nonsense/unsupported claims do not trigger automatic development. Do not adopt external PRs without review. Keep useful feedback open; moderate/close spam.
- Warn users about personal data before requesting logs/screenshots. Do not request email or unnecessary device data: public profiles/usernames are visible, issues do not automatically publish email addresses and are not a substitute for a support email.
- Handle security vulnerabilities only through the private reporting channel in the project's `SECURITY.md`, not in public issues.

## A6. Pull requests

- Title in commit style; body: what/why, issue, changes, test strategy, role decision, relevant checklist from CoderTeam 4.1. Mark unfinished work as Draft.
- **Squash** working branches into `dev`; use a **merge commit** for promotions. Authors cannot approve their own PR: document self-review as role perspectives, not as fake approvals.
- Wait for CI on the current PR head: `gh pr checks <n> --repo <internal> --watch`. For "no checks," wait briefly and check again; do not count it as success. Resolve unexpectedly missing or failing checks before merging.
- Keep `test -> main` open, including its diff and test results/QA, until the user explicitly approves; safest for the user to merge it themselves. Chat approval is not technical branch protection.

## A7. Public release

**Before every public push/release:** present the exact internal `main` SHA, version, file allowlist, package, and SHA-256, and obtain explicit approval. Build/test internal `main`; verify the clean Public staging area and exact target under B2.

1. **Content:** short GitHub description; user-facing README with value/features, requirements, startup instructions, and releases link. Only individually reviewed final source/assets, required project/build files, deliberately selected LICENSE, third-party notices, SECURITY, and reviewed public CI. Do not blindly copy internal README/workflows; public instructions in the package should use public links only.
2. **Exclusions:** control files (A9), internal briefs/ADRs, private history/issue/PR contents, tests without separate publication review, local settings, `.vs`/`bin`/`obj`, logs, PDB/symbols, and arbitrary build output in the source tree. Put packages in release assets, not binary commits to the source repository.
3. **Rights/metadata:** check source, comments, resources, assembly/project metadata, workflows/public logs, and package for secrets, private email/personal data, local paths/computer names. Do not transfer name/metadata approvals across projects. Clarify license/third-party material rights and credits; THIRD-PARTY-NOTICES does not license your own code. Unclear rights block publication. Do not blindly remove product identifiers; assess impact and regression-test first.
4. **History/releases:** only a curated file snapshot; never merge/cherry-pick private history. Public tag `vMAJOR.MINOR.PATCH` points to a Public commit; document internal SHA -> Public commit/tag internally. Public release notes must not contain private issue/PR links or numbers. Versioned executable package + SHA-256; current/older downloads on Releases, not a short-lived Actions artifact as a substitute.
5. **Screenshots/user changes:** reviewed product images are allowed. GitHub attachment URLs in README are references, not local image files. Before Public work, check remotes/user changes; if the checkout is clean and has no divergence, fast-forward update it. Do not replace/download internal images without being asked; consider versioned images for offline documentation.

**Verify the final candidate:** compare Public product sources with the approved internal MAIN state; deliberately curate any different Public build/docs files. With different Public build parameters, run relevant internal tests against the exact Public binaries without publishing test infrastructure. Compare the tagged rebuild with the tested package files; check ZIP entries against the package allowlist and inspect their contents. After publication, download the assets again and verify checksums and actual Latest/Draft/Prerelease status.

**Corrections during approval:** a new bugfix creates a new test/release candidate; do not carry old MAIN/Public approvals over. Do not accidentally publish outdated local packages/tags, and do not move tags. After renewed explicit test approval, update MAIN and refresh the A7 approval template with the new SHA, package, and hash.

Use milestones, private project boards, Actions, Dependabot, and CHANGELOG as appropriate for the project.

## A8. Branch protection

Where repository/plan permits, require PRs and successful CI (`dev` from a working branch, `test` from `dev`, `main` from `test`); prohibit force-push/deletion. Require independent approval only if a real reviewer is available; otherwise rely on PR/CI/process protections instead of fake review.

BatteryBuddy's private Free plan currently does not allow the desired protection; do not generalize this to other repositories or change visibility for that reason. Without protection, failing CI and human approval are **not a technically enforced merge prohibition**; the agent still observes the gates.

## A9. CI against control-file copies

**Documented requirement, workflow not yet implemented:** add `no-agent-control-files` when setting up CI or making the next targeted CI change. The repository may contain the technical check logic, not the central instructions.

- Internal on every `pull_request` and `push` to `dev`, `test`, `main`; Public on the actual release/default branch. No path filters that omit documentation changes.
- Read the full current tracked tree NUL-safely from `git ls-files -z`, not only the diff/old history. Git errors must fail, not appear to be an empty list.
- Exact basename, any subfolder, case-insensitive: **`agents.md`, `CoderTeam.md`, `GitHub Verhalten.md`, `LessonsLearned.md`, `TokenOptimierung.md`**. This also blocks `AGENTS.md` and moved copies.
- Print matching paths and use a failing exit code; no automatic deletion, silent exceptions, or blanket Markdown ban. README, LICENSE, SECURITY, PROVIDERS, and ADRs remain allowed.
- Isolated fixtures: clean tree succeeds; each prohibited name at root/in a subfolder and with different capitalization fails; legitimate docs succeed; Git invocation failure fails. Do not check in control-file test fixtures to a product branch.
- Use existing CI, `contents: read`, no secrets, and no `pull_request_target` for foreign PR code. Check the current head before merge; make the check required if protection is available. `.gitignore` is not a substitute; failing CI without protection does not technically block a merge (A8).

# B - Technical procedures

## B1. Tools

Clone/edit/build/test locally; prefer `gh` for GitHub operations, or actually available remote tools. MCP is not a local clone/build runner; do not assume features or write permissions. Use `rtk` for shell commands; for unsupported commands use `rtk bypass`; disable pagers (`git --no-pager`). Avoid unnecessary global identity/configuration output.

## B2. Environment check and project assignment

1. Check repository root, branch, changes, tracking, and `git worktree list --porcelain`; a `.git` file/directory or folder name alone proves nothing.
2. Check both fetch **and** push remotes; determine owner/project. A1 naming conventions help, but `origin`/suffix is not proof.
3. Confirm both target repositories with `gh repo view <owner>/<repo> --json nameWithOwner,url,visibility,defaultBranchRef,isFork`. Internal must be private; Public must be public/independent and not a fork of the private repo. Ask a focused question if assignment is missing/unclear.
4. Check internal remote `dev`, `test`, `main` branches, head SHA, and CI; determine the Public default branch separately. Internal and public `main` are different targets.
5. Before push/merge/release, re-confirm repository, operation, target branch, current SHA, CI, and applicable approval: `gh --repo <owner>/<repo>` or an explicit API path, Git `-C <Worktree>`. Stop if unclear; after an unknown API result, reconcile remote state instead of blindly writing again.

Check tools/auth and the project brief/ADRs/manifest/build/tests as appropriate; do not inherit old technology/path/license assumptions. If an actual firewall block occurs, pause and ask; do not work around it. Starting your own Ollama process is covered separately in Token Optimization.

## B3. Solve problems deliberately

| Problem | Procedure |
|---|---|
| No clone | Agree on target path; `gh repo clone <owner>/<repo> <Path>`, create worktrees if needed, and verify checkout. |
| Worktrees | Do not check out the same branch twice; protect changes and use the correct folder. Do not simply delete/rename folders; inspect before `git worktree remove <Path>`. |
| Auth/403 | `gh auth status`; ask the user to run `gh auth login` if needed. `gh auth setup-git` changes global configuration: only with approval. No plaintext tokens/token URLs. |
| No write permission | Prepare issue/PR and ask the user to perform/approve the action; do not bypass restrictions. |
| Large PR/reversions/conflict | Understand both sides/shared base; do not blindly use `--ours`/`--theirs`; do not merge imminent reversions. Resolve deliberately and build/test appropriately. |
| CRLF/LF or long paths | `.gitattributes` with `* text=auto`; quote paths and, if needed, set repo-local `core.longpaths true`. |
| Secret committed | Stop/inform; treat as compromised and revoke/rotate. Clean history only after discussion. |
| Control files in product repo | Consolidate variants centrally first; remove only the exact, content-identified list and repair broken links. Preserve product docs; do not delete Markdown indiscriminately. Keep old history; a cross-branch exception requires concrete user approval, not an earlier request. |

## B4. Security boundaries

No secrets in code, issues, PRs, logs, or commits. Force-push, repository/branch deletion, history rewriting, or visibility changes require explicit approval; never delete permanent branches, and keep Internal private/Public public.

Do not delegate GitHub/documentation administration autonomously to Ollama. New experimental agents only on request, with repository/path allowlists; do not give local models unrestricted shell access/credentials. The executor is not an OS sandbox. For approved cleanup, preserve necessary evidence outside the product repository, verify exact targets and deletions; do not include product worktrees/global caches.

## B5. Standard change workflow

1. Check B2, preserve user changes, fetch remote, and fast-forward the correct `dev` worktree; resolve conflict/divergence instead of overwriting.
2. Create issue per A5, design/role review, then `git switch -c <type>/<short-name>` from `dev`.
3. Make coherent changes; complete the CoderTeam checklist/self-review and appropriate build/tests or documentation review. Capture build exit code immediately and stop on failure; do not rely only on `Select -Last N` (it can hide errors/use old binaries). Concise error/warning/success filters do not replace exit-code checks.
4. Commit per A3, `git push -u origin <branch>`, open PR to `dev`, wait for current CI, squash-merge; remove temporary branch after confirmed merge. Close issue only when fully resolved; update affected docs/CHANGELOG in the change.
5. Promote product `dev -> test` through a merge PR under CoderTeam 4.1; update worktree, provide test build/absolute startup path, invite user testing, and record feedback.
6. Keep `test -> main` open until explicit approval of the tested state; QA comment **before** merge. Afterwards create a merge commit, annotated `vMAJOR.MINOR.PATCH` on the internal merge commit/push; update/build/test internal `main`. Never promote with `--delete-branch`; verify all three permanent branches.
7. Public only separately under A7; package fresh from approved state, do not overwrite/adopt existing untracked `dist` files without review. Control-file cleanup alone does not trigger product promotion, version bump, or product build.

## B6. PowerShell/gh quick reference

- No `<<<`/Unix heredoc; use a PowerShell here-string for multiline text (`@'` / `'@` on separate lines), e.g. pipe it to `git commit -F -`.
- Use `--jq '.title'` instead of `\"` escapes. If `gh pr edit` fails with a GraphQL error, use REST if needed: `gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f title="..."`.
- Check the original encoding/BOM; write the intended project format deliberately, e.g. explicit `New-Object Text.UTF8Encoding $false` for UTF-8 without BOM. Do not infer BOM policy broadly from API defaults.
- Quote PowerShell arguments containing `{}`, e.g. `'refs/tags/v1.0.4^{}'`, so they are not interpreted as script blocks.

## B7. VS Code command approvals

- Use selective terminal approvals instead of `AllowAllCommands`/global auto-approval. Tested with user confirmation in November 2026: `chat.tools.terminal.enableAutoApprove: true`, `chat.tools.global.autoApprove: false`, and JSON rules `"/^git\\b/": true` and `"/^rtk\\s+git\\b/": true` under `chat.tools.terminal.autoApprove`. Never allow `rtk` indiscriminately: it can run arbitrary other commands. Preserve existing rules/settings; change only the requested scope.
- These rules broadly allow Git, not only read-only subcommands. Technical auto-approval **does not** replace substantive approval for branch deletion, force-push, MAIN, or Public under A/B4. A Git rule does not approve `gh`.
- Have other commands confirmed through the built-in tool/terminal approval prompt, not a chat question as a substitute. Keep substantive questions and release approvals separate. Do not turn off existing protection to reduce prompts; do not enable `ignoreDefaultAutoApproveRules` by default.
- Rules are not a security boundary: harness, sandbox, integrated rules, and compound commands affect prompts; read-only/sandboxed calls may proceed without one. For problems, check current [VS Code documentation](https://code.visualstudio.com/docs/agents/run/approvals#_automatically-approve-terminal-commands) and the actual prompt; do not claim a universal effect.
- Approval test only on request: create a clearly named temporary local branch without checkout/commit/push, then delete exactly that branch with `branch -d`; verify the original branch is clean/unchanged. The agent sees a successful tool call; the user separately confirms whether a prompt actually appeared.

# C - BatteryBuddy: reference only, not required context

**Assignment last checked 2026-11-01; apply B2 again before actions:**

| Purpose | Repository / local folder under `D:\AI-stuff\BatteryBuddy` |
|---|---|
| Internal `dev` / `test` / `main` | `Dergln/BatteryBuddy-Intern`; `BatteryBuddy-dev`, `BatteryBuddy-test`, `BatteryBuddy-main`; shared history/`origin` |
| Public, default branch `main`, not a fork | `Dergln/BatteryBuddy-Public`; own clone `BatteryBuddy-Public` |

Both GitHub default branches are `main`. Internal `test`/`main` contain untracked `dist/`: user files. Public: description present, release `v0.1.24` dated 2026-10-29; clean fast-forward to `7c0e016` on 2026-11-01 including two README screenshot URLs (GitHub attachments, not image files in the tree). All internal fetch/push remotes updated to the new `-Intern` name.

**Technology/license:** .NET Framework 4.8 + WPF, Core `netstandard2.0`; project brief `docs/projektbrief.md`, ADR `docs/adr/0001-dotnet-framework-48-wpf.md`. Portable SDK `D:\AI-stuff\BatteryBuddy\.tools\dotnet`: check existence/version, add to PATH only per process. Release build `dotnet build src\BatteryBuddy.App -c Release`; startup path in the respective worktree `src\BatteryBuddy.App\bin\Release\net48\BatteryBuddy.exe`; Public package is a Windows ZIP.

`Version` in `Directory.Build.props` controls UI/assembly/file/product version `MAJOR.MINOR.PATCH.REVISION`, with commit ID in Informational Version. `dev`: increment revision for each visible test iteration; `test`: increment patch and set revision `.0` (e.g. `0.1.1.0`); `main` adopts the exact version, tag `v0.1.1`.

`LICENSE.md` confirms GNU GPLv3, replacing an older open/proprietary license note: commercial use/inspection/modification/distribution is allowed; distribution requires GPL obligations, including complete corresponding source code; private changes alone do not require publication. Third-party libraries/graphics retain their own rights/credits; Public adoption still requires separate approval.

**Historical evidence:**
- 2026-10-25: `Dergln/BatteryBuddy` was the old internal name; three worktrees set up, `gh` clone/auth worked, `gh auth setup-git` was not run. Branch protection/rulesets required a plan upgrade; on 2026-11-01 permanent branches were reported unprotected by the API.
- 2026-10-26: PR #71 deleted `dev` with `--delete-branch`, despite `delete_branch_on_merge=false`; this led to A2.
- 2026-10-28: independent Public repository and curated versioned releases introduced; this led to A1/A7.
- 2026-11-01: repository renamed, fixed `-Intern`/`-Public` convention; root entry point moved and central storage consolidated. Earlier synchronization from PR #4 was superseded.
- Cleanup: 20 local copies removed; [PR #198 (`dev`)](https://github.com/Dergln/BatteryBuddy-Intern/pull/198), [#199 (`test`)](https://github.com/Dergln/BatteryBuddy-Intern/pull/199), [#200 (`main`)](https://github.com/Dergln/BatteryBuddy-Intern/pull/200) merged after green CI. Each had five control-file deletions plus a README link removed; remaining product files were byte-identical, worktrees/remotes unchanged, Public unchanged by cleanup, old history retained. This completed task does not authorize future bypasses of promotion gates.
Editor is loading...
Leave a Comment