diff --git a/History.md b/History.md new file mode 100644 index 0000000..520e6f0 --- /dev/null +++ b/History.md @@ -0,0 +1,15 @@ +# Project History + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +## 2026-07-06 + +- **Wiki bootstrap (#224)** — Added repo-tracked `docs/wiki/` (10 pages), `scripts/sync-gitea-wiki.sh`, PR template gate, and sync safety tests for Gitea-Tools publication. + +## Prior milestones + +- Gated review/merge path (#16), task capability resolver (#69), issue-write tool gates. +- Canonical JSON execution profiles (#19) and thin MCP launchers. +- Role session router (#206) and review decision lock (#211). \ No newline at end of file diff --git a/Home.md b/Home.md index e69de29..24c2cd5 100644 --- a/Home.md +++ b/Home.md @@ -0,0 +1,35 @@ +# Gitea-Tools Project Wiki + +Welcome to the version-controlled wiki for the Gitea-Tools MCP server and CLI tooling. + +## Navigation + +- [Home](Home.md) +- [Operator Guide](Operator-Guide.md) +- [Repositories Map](Repositories.md) +- [Identity and Profiles](Identity-and-Profiles.md) +- [Workflow Model](Workflow.md) +- [Safety and Gates](Safety-and-Gates.md) +- [MCP Tools Reference](MCP-Tools.md) +- [Operator Runbooks](Runbooks.md) +- [Open Decisions](Open-Decisions.md) +- [Project History](History.md) + +## Gitea Wiki mirror + +These repo-tracked pages are the **source of truth**. The Gitea native Wiki +for this repository is a read-only convenience mirror generated from this +directory with `scripts/sync-gitea-wiki.sh` (dry-run by default; see +[Runbooks](Runbooks.md)). Never edit the Gitea Wiki directly — change the +pages here through a PR, then sync. + +## Project overview + +Gitea-Tools provides the Gitea MCP server, execution-profile configuration, +identity handling, and CLI helpers used across MCP Control Plane workflows. +It enforces author/reviewer separation, gated review/merge, task-capability +resolution, and fail-closed safety rails in code. + +Canonical long-form docs also live under `docs/` in the repository (for example +`docs/gitea-execution-profiles.md` and `docs/llm-workflow-runbooks.md`). The +wiki summarizes operator-facing rules; the repo docs carry implementation detail. \ No newline at end of file diff --git a/Identity-and-Profiles.md b/Identity-and-Profiles.md new file mode 100644 index 0000000..763a3bb --- /dev/null +++ b/Identity-and-Profiles.md @@ -0,0 +1,39 @@ +# Identity and Profiles + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +The LLM is not the role — the **MCP execution profile** is the role. Profiles +bind an authenticated Gitea identity to an allowed operation set. + +## Reference profiles (prgs) + +### Author / implementer + +- **Profile:** `prgs-author` +- **Typical identity:** `jcwalker3` +- **Allowed:** branch create/push, PR create, issue comment/create/close, repo commit, read. +- **Forbidden:** PR approve, merge, request_changes. + +### Reviewer / merger + +- **Profile:** `prgs-reviewer` +- **Typical identity:** `sysadmin` +- **Allowed:** PR review/approve/merge/request_changes, issue comment, read. +- **Forbidden:** branch push, PR create, repo commit. + +## Configuration + +Profiles are defined in the canonical JSON config (`GITEA_MCP_CONFIG`, typically +`~/.config/gitea-tools/profiles.json`). Launchers are thin: they set +`GITEA_MCP_PROFILE` and point at the config file. Credentials resolve from +keychain or env references — never inline in client configs. + +See `docs/gitea-execution-profiles.md` in the repository for the full model. + +## Profile switching + +Use separate MCP server namespaces (`gitea-tools` author vs `gitea-reviewer`) +or distinct launcher entries. Runtime in-place profile switching is disabled by +default (fail closed). \ No newline at end of file diff --git a/MCP-Tools.md b/MCP-Tools.md new file mode 100644 index 0000000..38af50e --- /dev/null +++ b/MCP-Tools.md @@ -0,0 +1,34 @@ +# MCP Tools Reference + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +## Identity and capability + +- `gitea_whoami` — authenticated user and active profile metadata. +- `gitea_get_profile` / `gitea_get_runtime_context` — allowed and forbidden operations. +- `gitea_resolve_task_capability` — required pre-flight for gated mutations. +- `gitea_route_task_session` — role/session router before task execution. + +## Author tools + +- `gitea_create_issue`, `gitea_create_issue_comment`, `gitea_close_issue` +- `gitea_mark_issue`, `gitea_set_issue_labels`, `gitea_lock_issue` +- `gitea_create_pr`, `gitea_edit_pr`, `gitea_commit_files` +- `gitea_delete_branch` + +## Reviewer tools + +- `gitea_check_pr_eligibility` — read-only eligibility check. +- `gitea_dry_run_pr_review` — validation-phase review mechanics. +- `gitea_mark_final_review_decision` — mark validation complete. +- `gitea_submit_pr_review` / `gitea_review_pr` — gated live review. +- `gitea_merge_pr` — gated merge (only merge path). + +## Read tools + +- `gitea_list_prs`, `gitea_view_pr`, `gitea_list_issues`, `gitea_view_issue` +- `gitea_get_file`, `gitea_list_labels`, `gitea_mirror_refs` + +See the repository `README.md` for the full tool table and client setup. \ No newline at end of file diff --git a/Open-Decisions.md b/Open-Decisions.md new file mode 100644 index 0000000..a465ff7 --- /dev/null +++ b/Open-Decisions.md @@ -0,0 +1,11 @@ +# Open Decisions + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +Pending architectural and workflow decisions: + +- **Operation-scoped role selection (#228)** — Move from launcher-profile-dependent routing to per-operation profile resolution. +- **Gitea-Tools wiki for dadeschools remote** — This bootstrap covers `prgs`; dadeschools instance wiki parity is undecided. +- **Server-side self-merge block** — Complement tool gates with Gitea branch protection where available. \ No newline at end of file diff --git a/Operator-Guide.md b/Operator-Guide.md new file mode 100644 index 0000000..35095ff --- /dev/null +++ b/Operator-Guide.md @@ -0,0 +1,31 @@ +# Operator Guide + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +Handbook for LLM operators and human developers using the Gitea-Tools MCP server. + +## Key rules + +1. **Verify identity first** — Run `gitea_whoami` and confirm the active profile before any mutation. +2. **Resolve task capability** — Call `gitea_resolve_task_capability` for the intended task before gated tools. +3. **One unit of work per session** — Implement one claimed issue *or* review/merge one PR; do not mix author and reviewer mutations in one session. +4. **No self-review / no self-merge** — The authenticated Gitea user must not approve or merge a PR they authored. +5. **Follow the gates** — Prompts express intent; MCP tools enforce safety. Never bypass gates via prompt instructions. + +## Supported Gitea instances + +| Remote | Host | Default org/repo | +|--------|------|------------------| +| `dadeschools` | `gitea.dadeschools.net` | `Contractor / Timesheet` | +| `prgs` | `gitea.prgs.cc` | `Scaled-Tech-Consulting / Timesheet` | + +Always pass `remote` explicitly on tool calls. The server default is `dadeschools`; forgetting `remote` on a `prgs` task hits the wrong host. + +## New session checklist + +1. `gitea_whoami` — confirm authenticated user and profile. +2. `gitea_get_runtime_context` — allowed/forbidden operations for this session. +3. `gitea_resolve_task_capability` — prove the session may perform the planned task. +4. For reviewer work: dry-run validation (`gitea_dry_run_pr_review`) before live review mutations. \ No newline at end of file diff --git a/Repositories.md b/Repositories.md new file mode 100644 index 0000000..88724d0 --- /dev/null +++ b/Repositories.md @@ -0,0 +1,37 @@ +# Repositories Map + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +Active MCP Control Plane repositories (authoritative inventory for wiki publication gate #224 / #87): + +| Repository | Purpose | Wiki required | +|------------|---------|---------------| +| `Scaled-Tech-Consulting/Gitea-Tools` | Gitea MCP server, execution profiles, workflow tooling | Yes — live Gitea Wiki on Wiki tab | +| `Scaled-Tech-Consulting/mcp-control-plane` | Orchestrators, audit trails, multi-service controller workflows | Yes — live Gitea Wiki on Wiki tab | + +Repo-tracked `docs/wiki/` is the source of truth; the Gitea Wiki is a mirror. +Wiki-related issues cannot be closed until the live Wiki is verified — see +[Safety and Gates](Safety-and-Gates.md) and [Runbooks](Runbooks.md). + +### Gitea-Tools + +- **Repository:** `Scaled-Tech-Consulting/Gitea-Tools` +- **Purpose:** Gitea MCP server, profile configuration, CLI scripts, safety gates. +- **Base branch:** `master` + +### mcp-control-plane + +- **Repository:** `Scaled-Tech-Consulting/mcp-control-plane` +- **Purpose:** Controller workflows, Jenkins/GlitchTip integrations, audit orchestration. +- **Base branch:** `master` + +## Wiki publication status (#224 readiness gate) + +| Repository | `docs/wiki/` source | Gitea Wiki published | Proof | +|---|---|---|---| +| `Scaled-Tech-Consulting/Gitea-Tools` | yes (10 pages) | pending publication — operator-confirmed sync required | pending | +| `Scaled-Tech-Consulting/mcp-control-plane` | yes (10 pages) | published (verified 2026-07-06) | [Wiki Home](https://gitea.prgs.cc/Scaled-Tech-Consulting/mcp-control-plane/wiki/Home) | + +Update this table whenever a wiki is published, re-synced, or found stale. \ No newline at end of file diff --git a/Runbooks.md b/Runbooks.md new file mode 100644 index 0000000..d42fe19 --- /dev/null +++ b/Runbooks.md @@ -0,0 +1,40 @@ +# Operator Runbooks + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +## PR review and merge + +1. `gitea_resolve_task_capability(task="review_pr")` +2. `gitea_check_pr_eligibility` for review and merge actions. +3. Validate locally: tests, `py_compile`, `git diff --check`. +4. `gitea_mark_final_review_decision` → approve via `gitea_review_pr`. +5. `gitea_merge_pr` with pinned head SHA and `confirmation="MERGE PR "`. + +## Gitea Wiki sync + +The Gitea Wiki mirrors `docs/wiki/` (source of truth). After merging wiki changes: + +1. Preview (no network): + ```bash + scripts/sync-gitea-wiki.sh + ``` +2. Operator-confirmed push: + ```bash + GITEA_WIKI_SYNC_CONFIRM="SYNC WIKI Gitea-Tools" scripts/sync-gitea-wiki.sh --push + ``` +3. If clone fails on first run, bootstrap Home via Gitea API or UI, then re-run. + +The script mirrors only `docs/wiki/*.md`, never deletes wiki pages, and never +prints credentials. + +## Wiki Publication Readiness Gate (#224) + +Actual Gitea Wiki publication is a **required repo readiness gate**. + +1. **Closure prevention** — No wiki issue may close on markdown/helper work alone. + Closing requires live-Wiki proof: Wiki Home link plus page listing or wiki git log. +2. **Reviewer checklist** — PR template requires verifying the repo **Wiki tab**. +3. **Publication authority** — `--push` requires exact `GITEA_WIKI_SYNC_CONFIRM` phrase. +4. **Per-repo status** — Update [Repositories Map](Repositories.md) when published. \ No newline at end of file diff --git a/Safety-and-Gates.md b/Safety-and-Gates.md new file mode 100644 index 0000000..25c21fb --- /dev/null +++ b/Safety-and-Gates.md @@ -0,0 +1,19 @@ +# Safety and Gates + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +*Prompts express intent; MCP tools enforce safety.* + +## Primary gates + +1. **Fail closed** — Unknown tasks, missing capability resolution, or profile mismatches block mutations. +2. **Task capability map** — `gitea_resolve_task_capability` must precede gated issue/PR mutations. +3. **Issue lock** — `gitea_lock_issue` required before author implementation on a tracked issue. +4. **Head SHA pinning** — Reviews and merges refuse when the PR head moved. +5. **Explicit merge confirmation** — `gitea_merge_pr` requires `confirmation="MERGE PR "`. +6. **No self-review / self-merge** — Authenticated user must differ from PR author for approve/merge. +7. **Review decision lock** — Live review mutations require validation-phase dry-run and `gitea_mark_final_review_decision`. +8. **Redaction** — Tokens, passwords, and keychain material never appear in tool output. +9. **Wiki publication (#224)** — `docs/wiki/` and the sync helper are prerequisites only. Closing a wiki issue requires live Gitea Wiki proof on the repo Wiki tab. See [Runbooks](Runbooks.md#wiki-publication-readiness-gate-224). \ No newline at end of file diff --git a/Workflow.md b/Workflow.md new file mode 100644 index 0000000..7722426 --- /dev/null +++ b/Workflow.md @@ -0,0 +1,28 @@ +# Workflow Model + +## Navigation + +- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md) + +## Step 1: Review queue first (reviewer profile) + +1. `gitea_resolve_task_capability(task="review_pr")` +2. List open PRs; pick the oldest eligible PR (not self-authored, mergeable). +3. Pin head SHA; validate diff scope and run tests locally. +4. `gitea_mark_final_review_decision` → `gitea_review_pr` / `gitea_submit_pr_review` +5. `gitea_merge_pr` only with `confirmation="MERGE PR "` and pinned head SHA. + +## Step 2: Implement issues (author profile) + +1. `gitea_resolve_task_capability` for the author task. +2. `gitea_lock_issue` before implementation mutations. +3. Claim with `gitea_mark_issue` / `status:in-progress` label. +4. Branch, implement, test, push, `gitea_create_pr`. +5. Release claim when done; never self-review the PR. + +## Step 3: Operator follow-ups + +Wiki publication, credential provisioning, and cross-repo mirror operations are +operator-confirmed actions — see [Runbooks](Runbooks.md). + +Full Gitea-specific runbooks: `docs/llm-workflow-runbooks.md` in the repository. \ No newline at end of file