Rules find a home; source comments go self-contained (#9) #15

pit · 2026-10-06T11:22:12Z

pit commented

2026-10-06 11:22:12 +00:00

Part of #7. Implements #9.

Summary

The rules move to the agent context file; the comments that leaned on them learn to stand alone.

 AGENTS.md
+## Standing rules
+  ### Secrets        # nothing plaintext; vault-encrypted only; no *.plaintext staging
+  ### Privacy        # no DDNS hostname / external IP; third-party public hosts allowed
+## Docs
+  -> docs/index.md
+  ### Issue tracker   (existing)
+  ### Domain docs     (existing)

 ansible/ansible.cfg                                 # "see README" dropped
 ansible/roles/forgejo/defaults/main.yml             # "(convention 4)" dropped
 docs/adr/0001-forgejo-actions-runner-on-guest.md    # "convention 4" / "README convention 7" dropped

"Version pins live in one place" is not carried over — it is self-evident from the role defaults.

Evidence

Before: grep -rniE 'convention ?[0-9]|README|AGENTS\.md' ansible tofu -> 2 hits (defaults/main.yml:2, ansible.cfg:7), plus 3 in the ADR.
After: the same command over ansible/ and tofu/ -> 0 hits.
No behavioural change: the only code edits are comment rewrites. tofu fmt -check and tofu validate (Guest stack) pass; the role YAML parses; neither .tf logic, .yml logic nor any .j2 template was touched.
Two-axis review of the diff (Standards + Spec) found no missing, partial or incorrect acceptance criterion.

Merge Danger

Door: two-way — four docs/comment files; git revert on the merge restores the previous text.

Blast Radius: none at runtime. The tofu stacks and the ansible role are byte-identical in behaviour; only comments and agent-facing docs changed.

Part of #7. Implements #9. ## Summary The rules move to the agent context file; the comments that leaned on them learn to stand alone. ```diff AGENTS.md +## Standing rules + ### Secrets # nothing plaintext; vault-encrypted only; no *.plaintext staging + ### Privacy # no DDNS hostname / external IP; third-party public hosts allowed +## Docs + -> docs/index.md + ### Issue tracker (existing) + ### Domain docs (existing) ansible/ansible.cfg # "see README" dropped ansible/roles/forgejo/defaults/main.yml # "(convention 4)" dropped docs/adr/0001-forgejo-actions-runner-on-guest.md # "convention 4" / "README convention 7" dropped ``` "Version pins live in one place" is **not** carried over — it is self-evident from the role defaults. ## Evidence - **Before:** `grep -rniE 'convention ?[0-9]|README|AGENTS\.md' ansible tofu` -> 2 hits (`defaults/main.yml:2`, `ansible.cfg:7`), plus 3 in the ADR. **After:** the same command over `ansible/` and `tofu/` -> 0 hits. - No behavioural change: the only code edits are comment rewrites. `tofu fmt -check` and `tofu validate` (Guest stack) pass; the role YAML parses; neither `.tf` logic, `.yml` logic nor any `.j2` template was touched. - Two-axis review of the diff (Standards + Spec) found no missing, partial or incorrect acceptance criterion. ## Merge Danger **Door:** two-way — four docs/comment files; `git revert` on the merge restores the previous text. **Blast Radius:** none at runtime. The tofu stacks and the ansible role are byte-identical in behaviour; only comments and agent-facing docs changed.

pit added 1 commit

2026-10-06 11:22:12 +00:00

Rules find a home; source comments go self-contained (#9 ) bdbb53754f

The numbered "Conventions" list in the README is where the standing working
rules lived, and its numbers had leaked into the code: role defaults cited
"convention 4", ansible.cfg pointed at the README, and the ADR cited
"convention 4" and "README convention 7". Once the list goes (issue #10),
every one of those references dangles.

Give the rules a home and detach the citations:

- AGENTS.md gains named rules (no numbers): Secrets (nothing plaintext in the
  repo; vault-encrypted files only; never commit plaintext staging files) and
  Privacy (do not publish the DDNS hostname or the external IP; third-party
  public hosts and public service domains are explicitly allowed). It gains a
  Docs pointer at docs/index.md, alongside the agent-docs and domain-docs
  pointers. "Version pins live in one place" is not carried over: it is
  self-evident from the role defaults.
- Every source comment under ansible/ and tofu/ that cited a convention by
  number or pointed at the README is rewritten to stand alone, so nothing
  dangles once the numbers are gone. The ADR is detached the same way, since
  it cited the same numbers.

No behavioural change: the tofu stacks and the ansible role behave exactly as
before; the only code edits are comment rewrites.

Part of #7.

pit referenced this pull request

2026-10-06 11:22:20 +00:00

Rules find a home; source comments go self-contained #9

pit reviewed

2026-10-06 11:26:35 +00:00

AGENTS.md Outdated

					
				@ -2,6 +2,27 @@

				Infra repo: OpenTofu + Ansible that provisions and maintains Forgejo and Nginx Proxy Manager (NPM) on the Pit hosts.

				## Standing rules

I don't like this naming. This implies the actions that we're taking here. A new reader doesn't need to know that these used to be rules in a readme with more rules and these are the last "standing rules". Naming should be something that simply implies that these are rules to follow by agents in this repo/project.

pit marked this conversation as resolved

pit reviewed

2026-10-06 11:28:18 +00:00

ansible/roles/forgejo/defaults/main.yml Outdated

					
				@ -1,5 +1,5 @@

				---

				# Version pins (convention 4): one place for the service, one for its runner.

				# Version pins: one place for the service, one for its runner.

Everithing after the : needs to go. It's implementation details that would need to grow if the list of pinned versions grow in the future

Everithing after the `:` needs to go. It's implementation details that would need to grow if the list of pinned versions grow in the future

pit marked this conversation as resolved

pit reviewed

2026-10-06 11:29:43 +00:00

docs/adr/0001-forgejo-actions-runner-on-guest.md Outdated

					
				@ -16,3 +16,2 @@

				  `uses: actions/checkout@v5` resolves without touching GitHub.

				- **Runner binary pinned** next to the Forgejo pin in role defaults

				  (convention 4), downloaded checksum-first like the service binary itself.

				- **Runner binary pinned** next to the Forgejo pin in role defaults,

Again a lot of implementation detail. ADRs should be documents that discuss architecture, not implementation. Just stating that the version needs to be pinned is enough

pit marked this conversation as resolved

pit reviewed

2026-10-06 11:31:05 +00:00

docs/adr/0001-forgejo-actions-runner-on-guest.md Outdated

					
				@ -49,3 +47,1 @@

				  download, fetched checksum-first) are third-party software mirrors, not the

				  operator's own public IP or DDNS name — the convention's actual target. Both

				  are public by design, and both hosts live in role defaults rather than being

				- **Public mirrors are not our addresses.** `data.forgejo.org` (the

I don't think this section even belongs to the ADR. Again too much implementation detail

pit marked this conversation as resolved

pit referenced this pull request from a commit

2026-10-06 11:41:10 +00:00

Trim prose per review on #15

pit added 1 commit

2026-10-06 11:41:10 +00:00

Trim prose per review on #15 38320caaff

- AGENTS.md: rename "Standing rules" to "Rules" — the old heading read as if
  the rules were the leftovers of a list.
- role defaults: drop the rest of the version-pins comment after the colon.
- ADR: state only that the runner binary is pinned; drop the checksum and
  install detail, and delete the public-mirrors bullet outright. The reasoning
  it carried (the two mirror hosts and why they are separate) already lives in
  the role-default comments next to the two variables.

pit commented

2026-10-06 11:41:28 +00:00

Comments addressed in 38320ca (the API rejected inline replies on this instance, so this is one comment instead of four).

AGENTS.md — ## Standing rules name (r150): renamed to ## Rules. You are right, "standing" was a leftover from the list it used to sit in.
role defaults — version-pins comment (r152): dropped, the comment is now just # Version pins.
ADR — runner-binary bullet (r154): trimmed to - **Runner binary pinned** in role defaults.
ADR — public-mirrors bullet (r156): deleted. Agreed it does not belong in a decision record. The reasoning it carried (the two mirror hosts and why they are separate variables) already lives in the role-default comments next to forgejo_actions_mirror and forgejo_runner_download_host — where someone changing a host actually looks. Say the word if you want that trimmed too.

Net effect across the two commits: no numbered-convention reference and no README/AGENTS pointer survives under ansible/ or tofu/; the ADR is down from 70 to 57 lines, decisions only. tofu fmt -check clean, role YAML parses, no behaviour touched.

Comments addressed in 38320ca (the API rejected inline replies on this instance, so this is one comment instead of four). - **AGENTS.md — `## Standing rules` name** (r150): renamed to `## Rules`. You are right, "standing" was a leftover from the list it used to sit in. - **role defaults — version-pins comment** (r152): dropped, the comment is now just `# Version pins`. - **ADR — runner-binary bullet** (r154): trimmed to `- **Runner binary pinned** in role defaults.` - **ADR — public-mirrors bullet** (r156): deleted. Agreed it does not belong in a decision record. The reasoning it carried (the two mirror hosts and why they are separate variables) already lives in the role-default comments next to `forgejo_actions_mirror` and `forgejo_runner_download_host` — where someone changing a host actually looks. Say the word if you want that trimmed too. Net effect across the two commits: no numbered-convention reference and no README/AGENTS pointer survives under `ansible/` or `tofu/`; the ADR is down from 70 to 57 lines, decisions only. `tofu fmt -check` clean, role YAML parses, no behaviour touched.

pit merged commit 389938f5b4 into main

2026-10-06 11:43:41 +00:00

pit deleted branch hermes/9-rules-find-a-home

2026-10-06 11:43:41 +00:00

pit referenced this pull request from a commit

2026-10-06 11:43:41 +00:00

Rules find a home; source comments go self-contained (#9) (#15)

pit referenced this pull request

2026-10-06 12:46:08 +00:00

README rewrite, docs tree, and protected main #7

Sign in to join this conversation.

No reviewers