olympus/infra-forge
3
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

README rewrite, docs tree, and protected main #7

New issue
Closed
opened 2026-10-06 10:04:52 +00:00 by pit · 1 comment
pit commented 2026-10-06 10:04:52 +00:00
Owner
Copy link

Problem Statement

The README has become the repo's junk drawer. It opens as the project's front door but then carries a numbered "Conventions" list that is really three unrelated things bundled together: agent working rules (where version pins live, how secrets are handled, the privacy rule), operator procedure (plan before apply, snapshot before touching a running service, back up state after apply), and a contribution rule (nothing directly to main). Because those rules are numbered, the numbers have leaked into the codebase: source comments and the ADR cite "convention 4" and "convention 7" by number, so editing the list breaks references elsewhere.

The list has also drifted from reality: it calls the repo private when it is not, describes the PRE Guest as if it were running, and frames the working flow as "phase 1, no CI" although Actions now exists on the instance. Detail that belongs in documentation — the NPM Edge flow, vault handling, the PRE rehearsal, the Actions runner and mirror hosts — sits in the README and grows it every time something changes.

Pedro wants a README that does one job (say what this is and how to run it, concisely) and a docs/ tree that holds the detail, is the single place to update, and becomes the published wiki. And the one rule a forge can enforce mechanically — no direct pushes to main — should be enforced by the forge, not kept as a sentence in a document. That last point matters more now that agents work in the repo: an agent landing a change on main without review is a real risk.

Solution

Rewrite the README from an adapted API/Server template, keeping it to the front door: what this is, requirements, environment variables, how to run each layer, a one-line repository overview, a "before you touch anything" pointer, contributing, and license. Move the detail into a docs/ tree whose entry point doubles as the wiki's Home page and as the docs table of contents. Decide what reaches the wiki from an explicit, in-repo manifest so that every document is either published or deliberately excluded. Turn "nothing directly to main" into real branch protection at the forge (admins included), enforced rather than described, and record that decision in an ADR.

User Stories

README

  1. As a visitor, I want the README to open with a one-line tagline and a short paragraph, so that I understand in seconds what this repo provisions and for whom.
  2. As an operator, I want the README to list requirements (Proxmox node, OpenTofu, Ansible, access to the Edge), so that I know what I need before starting.
  3. As an operator, I want the README to name the environment files and variables each layer needs (Proxmox API token, NPM credentials, vault password), so that I can prepare them in one place.
  4. As an operator, I want the README running section to give the three layers (Guest, Edge, service) as copy-pasteable commands, so that I can run the stack without opening a runbook.
  5. As a visitor, I want a short repository overview, so that I can find my way around without a per-file inventory that goes stale on every change.
  6. As a contributor, I want a Contributing section that states the branch + PR workflow, so that I know how changes land.
  7. As a reader, I want a License section pointing at a real LICENSE file, so that the terms are explicit.
  8. As Pedro, I do not want the README to link into the docs yet; once the wiki exists a single link to it can be added.

Rule migration

  1. As an agent, I want the standing working rules (secrets, privacy) to live in AGENTS.md, so that I read them where I already read project context.
  2. As Pedro, I want "version pins live in one place" dropped as a rule, because it is self-evident from the role defaults.
  3. As an operator, I want the procedure rules (plan before apply, snapshot before a service-touching run, encrypted state backup after apply) to live in the runbook that performs them, so that the rule and the step are one thing.
  4. As an operator, I want the vault rule to require the vault-pass file to be present and, if it is missing, to stop and ask the user to create it, so that I never run the playbook without it.
  5. As Pedro, I want the privacy rule to forbid publishing only the DDNS hostname and the external IP, and to explicitly allow third-party public hosts and public service domains, so that the rule matches its real intent.
  6. As an agent, I want AGENTS.md to say where the docs live, so that I can find them without guessing.
  7. As a maintainer, I want no source comment to reference a rule number or point at the README or AGENTS.md, so that comments stay self-contained and nothing dangles when docs move.

Branch protection

  1. As Pedro, I want main protected so that nothing can be pushed to it directly, admins included, so that every change lands through a reviewed pull request.
  2. As Pedro, I want protection to keep permitting PR merges with zero required approvals, so that I can still merge my own PRs as the sole operator.
  3. As Pedro, I want the protection decision recorded in an ADR, so that "why can't I push to main" has a canonical answer.
  4. As a future maintainer, I want to be able to add required status checks (tests, linters) to main later, so that quality gates can become mechanical.
  5. As Pedro, I want the branch-protection rule applied to the live repo now through the API and read back, so that protection is real before the prose describing it is removed.
  6. As Pedro, I want provisioning branch protection from the role filed as a separate follow-up, so that this change stays documentation-scoped.

Docs tree

  1. As a reader, I want a docs entry point that is a table of contents with a one-line description of each section and when to update it, so that I know where to look and where to write.
  2. As a reader, I want a runbooks section (index plus one file per runbook), so that procedures are findable and individually maintainable.
  3. As a reader, I want a decisions (ADR) section (index plus one file per decision), so that decisions are browsable.
  4. As a reader, I want an Actions section to exist now with an empty index, so that runner/mirror content has a home when it is written.
  5. As a reader, I want an architecture page describing the topology and how the Guest, Edge and service fit together, so that I understand the shape without reading the code.
  6. As a reader, I want the detail removed from the README (Edge flow, vault handling, PRE rehearsal, Actions/mirror notes) preserved in the docs, so that no useful information is lost.
  7. As a maintainer, I want each section index to live inside its own directory, so that every multi-page section has one predictable shape (index + pages).
  8. As a maintainer, I want a section with a single page (architecture) to stay a single file, so that ceremony is not added where it buys nothing.
  9. As a reader, I want a glossary of the project's own terms with the synonyms to avoid, so that all documents speak one vocabulary.
  10. As an agent, I want docs/agents/ to remain repo-only (issue tracker and domain docs), so that agent tooling is not published as user documentation.

Wiki publishing

  1. As a maintainer, I want the set of documents published to the wiki to live in the repo, not in the sync script, so that changing a document forces a publish decision.
  2. As a maintainer, I want the manifest to be allowlist by default (nothing published unless listed or excluded), so that no document reaches the wiki by accident.
  3. As a maintainer, I want a defined page mapping for the published set (docs index, architecture, runbook index and pages, ADR index and pages, Actions index, glossary), so that the published shape is predictable.
  4. As a wiki reader, I want the wiki Home to be the docs entry point, not the README, so that the wiki can grow runbooks independently of the repo landing page.
  5. As a wiki reader, I want a sidebar listing the published sections, so that I can navigate the wiki.
  6. As Pedro, I want the wiki mapping recorded as a change to the wiki-sync work (issue #2), so that this change does not build the sync itself.

Repo hygiene

  1. As a visitor, I want the Forgejo repository description in English with the new tagline, so that the repo metadata matches the now-English repo.
  2. As a visitor, I want the repo to carry an MIT LICENSE, so that reuse terms are explicit.
  3. As Pedro, I want the ADR numbering collision (two ADR-0001s: one on main, one on the parked wiki-sync branch) flagged on the wiki-sync work, so that it is resolved before both land.
  4. As an agent, I want the moved content to be free of the stale claims (private repo, running PRE, "no CI"), so that I never act on statements that are false.

Implementation Decisions

  • Template: the API/Server README template, adapted. Sections kept: tagline and short intro, Requirements, Environment variables, Running (three layers), a one-line repository overview, a before-you-touch-anything pointer, Contributing, License. Dropped: badges (self-hosted forge, not anonymously reachable, so no shields badge is possible), screenshot (nothing to show), table of contents (the forge renders one), and the API reference table (there is no API of our own; the repository overview replaces it). There is no "running locally".
  • The README carries no links into docs/. A single wiki link is added later, once the wiki is live.
  • Standing rules move to AGENTS.md as named rules (not numbered): Secrets and Privacy. "Version pins" is dropped as self-evident. AGENTS.md also gains a pointer to the docs entry point, alongside its existing pointers to docs/agents/ and the domain docs.
  • Procedure rules stop being rules and become the runbook's own gate lines (the plan review, the snapshot, the state backup are steps the runbook says out loud, not clauses referenced by number elsewhere).
  • Numbered conventions are removed entirely. The source comments that cited them are rewritten to be self-contained: no rule numbers and no reference to the README or AGENTS.md. This is a comments-only edit; no tofu or ansible behavior changes.
  • Branch protection on main: direct pushes disabled, applied to admins, zero required approvals, required status checks off for now, signed commits not required. Applied to the live repo through the API and read back. Provisioning it from the role is a follow-up issue, not part of this change.
  • An ADR records the main-protection decision. Its stated why is agent safety (a non-human pusher cannot land on main without review) and the ability to attach required workflows later.
  • Target document tree (the contract for the restructure; recorded because the layout is the decision, not because paths are meant to be stable):
README.md            repo landing page, no docs links yet
LICENSE              MIT
AGENTS.md            standing rules + where the docs live
GLOSSARY.md          canonical terms
docs/
  index.md           docs entry point + section TOC (wiki Home)
  architecture.md    topology and how the pieces fit
  runbooks/
    index.md         list of runbooks
    0001-*.md        deploy / Edge / vault / state / rollback runbook
  adr/
    index.md         list of decisions
    0001-*.md        runner on the guest (existing)
    0002-*.md        main protected at the forge
  actions/
    index.md         empty stub
  agents/            repo-only, never published
  wiki-pages.yml     publish manifest
  • Publish manifest lives in the repo with allowlist semantics: a document is published only if the manifest lists it, and the manifest also carries explicit exclusions. A coverage check fails if any document is neither published nor excluded, so adding, renaming or moving a doc forces a publish decision. The sync reads the manifest; humans edit the manifest.
  • Wiki page mapping (flat page names plus a sidebar for navigation; nested wiki page names are not supported by the forge today): docs index → Home, architecture → Architecture, runbooks index → Runbooks, runbook pages → Runbook-NNNN-*, ADR index → Decisions, ADR pages → ADR-NNNN-*, Actions index → Actions, glossary → Glossary. docs/agents/ is excluded. Mirror semantics are preserved (a deleted source deletes its page).
  • The wiki is not built here. The manifest and the mapping are recorded for the wiki-sync work (issue #2), which also retires the post-receive hook.
  • Glossary is created from the vocabulary already in use (Edge, Guest, Node, NPM, Prod, PRE, Stack, Blueprint, Operator key, Vault), as a glossary only — no implementation detail.
  • MIT LICENSE added; the Forgejo repository description updated to the README tagline (it is still in Spanish).
  • The parked wiki-sync branch's ADR-0001 collides in number with the ADR-0001 on main; it is flagged on issue #2, not renumbered here.

Testing Decisions

  • A good test asserts external behaviour only. Here the external behaviour is document-level: the set of files, their links, and the published mapping — never the prose inside them.
  • Citation check: no source comment under the ansible and tofu trees contains a numbered-convention reference nor points at the README or AGENTS.md.
  • Link check: every relative link in the README, the docs tree and the glossary resolves to a file that exists (no dangling links after the split).
  • Manifest coverage check: every markdown document in the docs tree (plus the glossary) is either published or explicitly excluded by the manifest. This is the forcing function and the highest seam available.
  • Push-rejection check: a direct push to main against the live forge is rejected, for an admin. Run manually once, since it needs a live remote.
  • API read-back: after the branch-protection call and the repository-description update, both are read back and asserted against the intended values.
  • Prior art: none of these exist yet. The wiki-sync branch's tests target the sync script, which is issue #2's scope; this change adds no tests for the sync. Whether the citation, link and manifest checks become committed scripts (the repo's first tests) is left open — the first pass may be one-shot commands reported in the PR.

Out of Scope

  • Building the wiki sync itself (issue #2): the script refactor, the hook retirement, the workflow, and the sidebar.
  • Provisioning branch protection from the forgejo role (follow-up issue).
  • Any CI workflows on main (lint, tests). Protection only opens the door for them later.
  • Actions section content (runner, mirror, labels). Only the empty index is created now.
  • PRE Guest work of any kind.
  • Renumbering the parked ADR or otherwise resolving the 0001 collision beyond flagging it.
  • Any behavioural change to the tofu stacks or the ansible role; the only code edits are self-contained comment rewrites.

Further Notes

  • Facts verified during the session: the repo reports private: false but is not anonymously reachable (it does not appear in the forge's public explore listing); the forge is 15.0.9; the ready-for-agent label already exists (id 1) — a note in docs/agents/issue-tracker.md claiming "no labels defined yet" is stale and should be corrected when that file is next touched; there is currently no branch protection on main.
  • Sequencing: the README, the docs tree, the glossary and the comment edits land in one PR, because a partial landing dangles citations and half-moved rules. The branch-protection API call and the repository-description update are manual steps executed at merge time and read back, not part of the diff.
  • The open question "state backup remote location (remote backend vs OpenBao)" is an undecided question, not a decision; it earns no ADR.
  • Prior art: the parked wiki-sync branch already drafted a glossary and an architecture page and defined a page mapping. This spec reuses that vocabulary and mapping, adapts the names to the index-plus-pages shape, and moves the publish decision into an in-repo manifest.
## Problem Statement The README has become the repo's junk drawer. It opens as the project's front door but then carries a numbered "Conventions" list that is really three unrelated things bundled together: agent working rules (where version pins live, how secrets are handled, the privacy rule), operator procedure (plan before apply, snapshot before touching a running service, back up state after apply), and a contribution rule (nothing directly to main). Because those rules are numbered, the numbers have leaked into the codebase: source comments and the ADR cite "convention 4" and "convention 7" by number, so editing the list breaks references elsewhere. The list has also drifted from reality: it calls the repo private when it is not, describes the PRE Guest as if it were running, and frames the working flow as "phase 1, no CI" although Actions now exists on the instance. Detail that belongs in documentation — the NPM Edge flow, vault handling, the PRE rehearsal, the Actions runner and mirror hosts — sits in the README and grows it every time something changes. Pedro wants a README that does one job (say what this is and how to run it, concisely) and a `docs/` tree that holds the detail, is the single place to update, and becomes the published wiki. And the one rule a forge can enforce mechanically — no direct pushes to main — should be enforced by the forge, not kept as a sentence in a document. That last point matters more now that agents work in the repo: an agent landing a change on main without review is a real risk. ## Solution Rewrite the README from an adapted API/Server template, keeping it to the front door: what this is, requirements, environment variables, how to run each layer, a one-line repository overview, a "before you touch anything" pointer, contributing, and license. Move the detail into a `docs/` tree whose entry point doubles as the wiki's Home page and as the docs table of contents. Decide what reaches the wiki from an explicit, in-repo manifest so that every document is either published or deliberately excluded. Turn "nothing directly to main" into real branch protection at the forge (admins included), enforced rather than described, and record that decision in an ADR. ## User Stories ### README 1. As a visitor, I want the README to open with a one-line tagline and a short paragraph, so that I understand in seconds what this repo provisions and for whom. 2. As an operator, I want the README to list requirements (Proxmox node, OpenTofu, Ansible, access to the Edge), so that I know what I need before starting. 3. As an operator, I want the README to name the environment files and variables each layer needs (Proxmox API token, NPM credentials, vault password), so that I can prepare them in one place. 4. As an operator, I want the README running section to give the three layers (Guest, Edge, service) as copy-pasteable commands, so that I can run the stack without opening a runbook. 5. As a visitor, I want a short repository overview, so that I can find my way around without a per-file inventory that goes stale on every change. 6. As a contributor, I want a Contributing section that states the branch + PR workflow, so that I know how changes land. 7. As a reader, I want a License section pointing at a real LICENSE file, so that the terms are explicit. 8. As Pedro, I do not want the README to link into the docs yet; once the wiki exists a single link to it can be added. ### Rule migration 9. As an agent, I want the standing working rules (secrets, privacy) to live in AGENTS.md, so that I read them where I already read project context. 10. As Pedro, I want "version pins live in one place" dropped as a rule, because it is self-evident from the role defaults. 11. As an operator, I want the procedure rules (plan before apply, snapshot before a service-touching run, encrypted state backup after apply) to live in the runbook that performs them, so that the rule and the step are one thing. 12. As an operator, I want the vault rule to require the vault-pass file to be present and, if it is missing, to stop and ask the user to create it, so that I never run the playbook without it. 13. As Pedro, I want the privacy rule to forbid publishing only the DDNS hostname and the external IP, and to explicitly allow third-party public hosts and public service domains, so that the rule matches its real intent. 14. As an agent, I want AGENTS.md to say where the docs live, so that I can find them without guessing. 15. As a maintainer, I want no source comment to reference a rule number or point at the README or AGENTS.md, so that comments stay self-contained and nothing dangles when docs move. ### Branch protection 16. As Pedro, I want main protected so that nothing can be pushed to it directly, admins included, so that every change lands through a reviewed pull request. 17. As Pedro, I want protection to keep permitting PR merges with zero required approvals, so that I can still merge my own PRs as the sole operator. 18. As Pedro, I want the protection decision recorded in an ADR, so that "why can't I push to main" has a canonical answer. 19. As a future maintainer, I want to be able to add required status checks (tests, linters) to main later, so that quality gates can become mechanical. 20. As Pedro, I want the branch-protection rule applied to the live repo now through the API and read back, so that protection is real before the prose describing it is removed. 21. As Pedro, I want provisioning branch protection from the role filed as a separate follow-up, so that this change stays documentation-scoped. ### Docs tree 22. As a reader, I want a docs entry point that is a table of contents with a one-line description of each section and when to update it, so that I know where to look and where to write. 23. As a reader, I want a runbooks section (index plus one file per runbook), so that procedures are findable and individually maintainable. 24. As a reader, I want a decisions (ADR) section (index plus one file per decision), so that decisions are browsable. 25. As a reader, I want an Actions section to exist now with an empty index, so that runner/mirror content has a home when it is written. 26. As a reader, I want an architecture page describing the topology and how the Guest, Edge and service fit together, so that I understand the shape without reading the code. 27. As a reader, I want the detail removed from the README (Edge flow, vault handling, PRE rehearsal, Actions/mirror notes) preserved in the docs, so that no useful information is lost. 28. As a maintainer, I want each section index to live inside its own directory, so that every multi-page section has one predictable shape (index + pages). 29. As a maintainer, I want a section with a single page (architecture) to stay a single file, so that ceremony is not added where it buys nothing. 30. As a reader, I want a glossary of the project's own terms with the synonyms to avoid, so that all documents speak one vocabulary. 31. As an agent, I want `docs/agents/` to remain repo-only (issue tracker and domain docs), so that agent tooling is not published as user documentation. ### Wiki publishing 32. As a maintainer, I want the set of documents published to the wiki to live in the repo, not in the sync script, so that changing a document forces a publish decision. 33. As a maintainer, I want the manifest to be allowlist by default (nothing published unless listed or excluded), so that no document reaches the wiki by accident. 34. As a maintainer, I want a defined page mapping for the published set (docs index, architecture, runbook index and pages, ADR index and pages, Actions index, glossary), so that the published shape is predictable. 35. As a wiki reader, I want the wiki Home to be the docs entry point, not the README, so that the wiki can grow runbooks independently of the repo landing page. 36. As a wiki reader, I want a sidebar listing the published sections, so that I can navigate the wiki. 37. As Pedro, I want the wiki mapping recorded as a change to the wiki-sync work (issue #2), so that this change does not build the sync itself. ### Repo hygiene 38. As a visitor, I want the Forgejo repository description in English with the new tagline, so that the repo metadata matches the now-English repo. 39. As a visitor, I want the repo to carry an MIT LICENSE, so that reuse terms are explicit. 40. As Pedro, I want the ADR numbering collision (two ADR-0001s: one on main, one on the parked wiki-sync branch) flagged on the wiki-sync work, so that it is resolved before both land. 41. As an agent, I want the moved content to be free of the stale claims (private repo, running PRE, "no CI"), so that I never act on statements that are false. ## Implementation Decisions - **Template**: the API/Server README template, adapted. Sections kept: tagline and short intro, Requirements, Environment variables, Running (three layers), a one-line repository overview, a before-you-touch-anything pointer, Contributing, License. Dropped: badges (self-hosted forge, not anonymously reachable, so no shields badge is possible), screenshot (nothing to show), table of contents (the forge renders one), and the API reference table (there is no API of our own; the repository overview replaces it). There is no "running locally". - The README carries **no links into `docs/`**. A single wiki link is added later, once the wiki is live. - **Standing rules move to AGENTS.md as named rules** (not numbered): *Secrets* and *Privacy*. "Version pins" is dropped as self-evident. AGENTS.md also gains a pointer to the docs entry point, alongside its existing pointers to `docs/agents/` and the domain docs. - **Procedure rules stop being rules** and become the runbook's own gate lines (the plan review, the snapshot, the state backup are steps the runbook says out loud, not clauses referenced by number elsewhere). - **Numbered conventions are removed entirely.** The source comments that cited them are rewritten to be self-contained: no rule numbers and no reference to the README or AGENTS.md. This is a comments-only edit; no tofu or ansible behavior changes. - **Branch protection on main**: direct pushes disabled, applied to admins, zero required approvals, required status checks off for now, signed commits not required. Applied to the live repo through the API and read back. Provisioning it from the role is a follow-up issue, not part of this change. - **An ADR records the main-protection decision.** Its stated *why* is agent safety (a non-human pusher cannot land on main without review) and the ability to attach required workflows later. - **Target document tree** (the contract for the restructure; recorded because the layout is the decision, not because paths are meant to be stable): ``` README.md repo landing page, no docs links yet LICENSE MIT AGENTS.md standing rules + where the docs live GLOSSARY.md canonical terms docs/ index.md docs entry point + section TOC (wiki Home) architecture.md topology and how the pieces fit runbooks/ index.md list of runbooks 0001-*.md deploy / Edge / vault / state / rollback runbook adr/ index.md list of decisions 0001-*.md runner on the guest (existing) 0002-*.md main protected at the forge actions/ index.md empty stub agents/ repo-only, never published wiki-pages.yml publish manifest ``` - **Publish manifest lives in the repo** with allowlist semantics: a document is published only if the manifest lists it, and the manifest also carries explicit exclusions. A coverage check fails if any document is neither published nor excluded, so adding, renaming or moving a doc forces a publish decision. The sync reads the manifest; humans edit the manifest. - **Wiki page mapping** (flat page names plus a sidebar for navigation; nested wiki page names are not supported by the forge today): docs index → Home, architecture → Architecture, runbooks index → Runbooks, runbook pages → `Runbook-NNNN-*`, ADR index → Decisions, ADR pages → `ADR-NNNN-*`, Actions index → Actions, glossary → Glossary. `docs/agents/` is excluded. Mirror semantics are preserved (a deleted source deletes its page). - **The wiki is not built here.** The manifest and the mapping are recorded for the wiki-sync work (issue #2), which also retires the post-receive hook. - **Glossary** is created from the vocabulary already in use (Edge, Guest, Node, NPM, Prod, PRE, Stack, Blueprint, Operator key, Vault), as a glossary only — no implementation detail. - **MIT LICENSE** added; the **Forgejo repository description** updated to the README tagline (it is still in Spanish). - The parked wiki-sync branch's ADR-0001 **collides in number** with the ADR-0001 on main; it is flagged on issue #2, not renumbered here. ## Testing Decisions - A good test asserts external behaviour only. Here the external behaviour is document-level: the set of files, their links, and the published mapping — never the prose inside them. - **Citation check**: no source comment under the ansible and tofu trees contains a numbered-convention reference nor points at the README or AGENTS.md. - **Link check**: every relative link in the README, the docs tree and the glossary resolves to a file that exists (no dangling links after the split). - **Manifest coverage check**: every markdown document in the docs tree (plus the glossary) is either published or explicitly excluded by the manifest. This is the forcing function and the highest seam available. - **Push-rejection check**: a direct push to main against the live forge is rejected, for an admin. Run manually once, since it needs a live remote. - **API read-back**: after the branch-protection call and the repository-description update, both are read back and asserted against the intended values. - Prior art: none of these exist yet. The wiki-sync branch's tests target the sync script, which is issue #2's scope; this change adds no tests for the sync. Whether the citation, link and manifest checks become committed scripts (the repo's first tests) is left open — the first pass may be one-shot commands reported in the PR. ## Out of Scope - Building the wiki sync itself (issue #2): the script refactor, the hook retirement, the workflow, and the sidebar. - Provisioning branch protection from the forgejo role (follow-up issue). - Any CI workflows on main (lint, tests). Protection only opens the door for them later. - Actions section content (runner, mirror, labels). Only the empty index is created now. - PRE Guest work of any kind. - Renumbering the parked ADR or otherwise resolving the 0001 collision beyond flagging it. - Any behavioural change to the tofu stacks or the ansible role; the only code edits are self-contained comment rewrites. ## Further Notes - Facts verified during the session: the repo reports `private: false` but is not anonymously reachable (it does not appear in the forge's public explore listing); the forge is 15.0.9; the `ready-for-agent` label already exists (id 1) — a note in `docs/agents/issue-tracker.md` claiming "no labels defined yet" is stale and should be corrected when that file is next touched; there is currently no branch protection on main. - Sequencing: the README, the docs tree, the glossary and the comment edits land in **one** PR, because a partial landing dangles citations and half-moved rules. The branch-protection API call and the repository-description update are manual steps executed at merge time and read back, not part of the diff. - The open question "state backup remote location (remote backend vs OpenBao)" is an undecided question, not a decision; it earns no ADR. - Prior art: the parked wiki-sync branch already drafted a glossary and an architecture page and defined a page mapping. This spec reuses that vocabulary and mapping, adapts the names to the index-plus-pages shape, and moves the publish decision into an in-repo manifest.
pit commented 2026-10-06 12:46:08 +00:00
Author
Owner
Copy link

Closed. All five children are merged (#8–#12, via PRs #13, #15, #16, #18, #20) and the one stale line they left behind is fixed on main (#25).

Story 21 — provisioning branch protection from the role — is consciously dropped rather than deferred. Protection is per-repo (the API exposes branch/tag protection only under /repos/{owner}/{repo}; there is no org- or instance-level default), so a role would be hardcoding one repo's policy into a generic installer for no gain. The protection itself is live and recorded in ADR 0002, including the caveat that it is not recreated by a re-provision.

Closed. All five children are merged (#8–#12, via PRs #13, #15, #16, #18, #20) and the one stale line they left behind is fixed on main (#25). Story 21 — provisioning branch protection from the role — is consciously dropped rather than deferred. Protection is per-repo (the API exposes branch/tag protection only under `/repos/{owner}/{repo}`; there is no org- or instance-level default), so a role would be hardcoding one repo's policy into a generic installer for no gain. The protection itself is live and recorded in ADR 0002, including the caveat that it is not recreated by a re-provision.
pit closed this issue 2026-10-06 12:46:08 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
forgejo-npm-edge
No results found.
Labels
Clear labels   
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Ready for an agent to pick up; see docs/agents/

  
ready-for-human
Requires human implementation

  
wontfix
Will not be actioned

  
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, ready for an AFK agent

  
ready-for-human
Requires human implementation

  
review/merge-ready
No blocking findings; human merge pending

  
review/needs-fix
Reviewer found blocking findings; fixer dispatched

  
review/needs-human
Circuit stopped: needs a human decision

  
review/needs-review
Awaiting review by the review agent

  
wayfinder:grilling
HITL ticket: conversation; grilling + domain-modeling

  
wayfinder:map
The map itself: destination, decisions so far, and the fog

  
wayfinder:prototype
HITL ticket: a cheap concrete artifact to react to

  
wayfinder:research
AFK ticket: read docs/APIs for a fact a decision waits on

  
wayfinder:task
HITL or AFK ticket: manual work that unblocks a decision

  
wontfix
Will not be actioned

No labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wontfix
needs-info
needs-triage
ready-for-agent
ready-for-human
review/merge-ready
review/needs-fix
review/needs-human
review/needs-review
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
olympus/infra-forge#7
No description provided.