From 2d5263218d83f023f85880c748cbce369ce7a7d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Normen=20M=C3=BCller?= Date: Wed, 6 May 2026 19:47:20 +0200 Subject: [PATCH] chore(gdl): dissolve ops/, relocate runbook to utl/gh/ - Remove adm/gdl/ops/github-repo-metadata.md (single-file directory) - Create utl/gh/RUNBOOK.md colocated with repo-metadata scripts - Update index.yaml: remove ops/ library entry, add task comment ref - Update workflow.md section 6: reference utl/gh/RUNBOOK.md directly - Update README.md: remove ops/ from Quick Navigation table Resolves #50 --- README.md | 1 - adm/gdl/README.md | 1 - adm/gdl/dev/protocols/workflow.md | 4 +-- adm/gdl/index.yaml | 7 ++--- adm/gdl/ops/github-repo-metadata.md | 43 ----------------------------- utl/gh/RUNBOOK.md | 39 ++++++++++++++++++++++++++ 6 files changed, 42 insertions(+), 53 deletions(-) delete mode 100644 adm/gdl/ops/github-repo-metadata.md create mode 100644 utl/gh/RUNBOOK.md diff --git a/README.md b/README.md index 7642494..5123ae7 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,6 @@ Operational implications: - `doc/agn/` is the agent-facing onboarding and navigation surface. - `doc/arc/` is human-readable architecture and system-reference documentation. - `adm/gdl/dev/` is agent-facing development governance. -- `adm/gdl/ops/` is agent-facing operations governance. ai4X is, in that sense, built by agentic AI agents for agentic AI agents.[^eyodf] diff --git a/adm/gdl/README.md b/adm/gdl/README.md index 1e17987..7fbb7c5 100644 --- a/adm/gdl/README.md +++ b/adm/gdl/README.md @@ -7,7 +7,6 @@ This directory contains normative guidance documents for ai4X development, opera | Section | Purpose | Key Documents | |---------|---------|---| | **dev/** | Development standards, code quality, workflow | `contracts/engineering-quality.md`, `contracts/typescript-quality.md`, `protocols/development-conformance.md`, `protocols/development-conformance-template.md`, `protocols/workflow.md` | -| **ops/** | Repository operations, automation, infrastructure | `github-repo-metadata.md` | | **pln/** | Planning governance, backlog management, issue promotion | `protocols/workflow.md`, `protocols/planning-conformance.md` | | **shr/** | Cross-cutting governance (planning + development) | `protocols/board-policy.md` | | **glossary.md** | Canonical term definitions (Planning Terms, Qualifier Terms) | `glossary.md` | diff --git a/adm/gdl/dev/protocols/workflow.md b/adm/gdl/dev/protocols/workflow.md index 2b7d7bc..60e7649 100644 --- a/adm/gdl/dev/protocols/workflow.md +++ b/adm/gdl/dev/protocols/workflow.md @@ -21,7 +21,6 @@ Normative development governance for this repository lives in: 1. .github/agents/ai4x.agent.md 2. adm/gdl/dev/contracts/* 3. adm/gdl/dev/protocols/* -4. adm/gdl/ops/* All artifacts under adm/gdl are normative governance artifacts. @@ -75,8 +74,7 @@ No hidden defaults in config or CLI resolution. - keep GitHub Actions workflows aligned with the current repository layout and active verification entrypoints 6. Repository metadata changes -- keep acc/repo-metadata.yaml aligned with intended GitHub About and Topics -- run the metadata check/apply path when repository metadata is intentionally changed +- follow the runbook in `utl/gh/RUNBOOK.md` ## Expert Team Routing diff --git a/adm/gdl/index.yaml b/adm/gdl/index.yaml index dfe6622..5d15d94 100644 --- a/adm/gdl/index.yaml +++ b/adm/gdl/index.yaml @@ -53,7 +53,8 @@ tasks: - glossary.md repo_automation: - - ops/github-repo-metadata.md + # Project-specific runbook outside governance scope. + # See: utl/gh/RUNBOOK.md terminology: - glossary.md @@ -116,10 +117,6 @@ library: shape: protocol depends_on: [dev/contracts/capability-authoring-governance.md, dev/protocols/workflow.md] - - path: ops/github-repo-metadata.md - shape: runbook - depends_on: [] - - path: glossary.md shape: base-contract depends_on: [] diff --git a/adm/gdl/ops/github-repo-metadata.md b/adm/gdl/ops/github-repo-metadata.md deleted file mode 100644 index 0123394..0000000 --- a/adm/gdl/ops/github-repo-metadata.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -version: 1.0.0 -last_updated: 2026-05-06 ---- - -# GitHub Repository Metadata Runbook - -## Purpose - -Keep repository About and Topics reproducible from versioned local metadata. - -## Source of Truth - -- acc/repo-metadata.yaml - -Required fields: - -1. version -2. repo -3. about -4. topics - -## Commands - -Check local metadata contract: - -bash ./utl/gh/repo-metadata.sh --check-local - -Check remote drift (requires gh auth): - -bash ./utl/gh/repo-metadata.sh --check - -Apply local metadata to GitHub (requires gh auth): - -bash ./utl/gh/repo-metadata.sh --apply - -## Operational Rules - -1. Keep acc/repo-metadata.yaml in sync with intended GitHub metadata. -2. Run --check-local before finishing metadata-related changes. -3. Run --check when remote drift must be validated. -4. Use --apply when metadata updates are intentional and the remote repository must be reconciled. -5. Do not finish metadata changes while intended local metadata and remote GitHub metadata still differ. diff --git a/utl/gh/RUNBOOK.md b/utl/gh/RUNBOOK.md new file mode 100644 index 0000000..f60eeca --- /dev/null +++ b/utl/gh/RUNBOOK.md @@ -0,0 +1,39 @@ +# GitHub Repository Metadata + +## Purpose + +Keep the GitHub repository About and Topics reproducible from versioned local metadata. + +## Source of Truth + +`acc/repo-metadata.yaml` — all intended repository metadata is declared here. + +## Commands + +```bash +# Check local metadata contract (no network) +bash ./utl/gh/repo-metadata.sh --check-local + +# Check remote drift (requires gh auth) +bash ./utl/gh/repo-metadata.sh --check + +# Apply local metadata to GitHub (requires gh auth) +bash ./utl/gh/repo-metadata.sh --apply +``` + +## Operational Rules + +1. Keep `acc/repo-metadata.yaml` in sync with intended GitHub metadata. +2. Run `--check-local` before finishing metadata-related changes. +3. Run `--check` when remote drift must be validated. +4. Use `--apply` when metadata updates are intentional and the remote repository must be reconciled. +5. Do not finish metadata changes while intended local metadata and remote GitHub metadata still differ. + +## When to Use + +The Tech Lead triggers metadata operations when: +- Repository About or Topics need to change +- `make verify` reports a metadata drift +- A Story or chore explicitly requires metadata reconciliation + +No automated sync — all metadata changes are intentional and human-triggered.