go-dns/docs/changes/00001-setup-project/plan.md

Plan: Initial project setup and DNS operation catalog

Summary

Complete go-dns project scaffolding and documentation alignment for change 00001-setup-project: git repository and feature branch, verify workspace registration and existing specify-phase artifacts (go.mod, Cursor rule, project spec, README, backlog, .gitignore), and create docs/bind-tsig-configuration.md per spec section 9. Preserve the full DNS operation catalog in spec.md (sections 1–10) without rewriting it.

This change is setup + documentation only. It does not implement RFC 2136, AXFR, TSIG signing, typed RR builders, zone data types in Go, unit tests, BIND testcontainer integration tests, CLI, or Docker.

Prerequisites

• Approved spec.md in this change folder.
• Workspace root go.work already lists ./go-dns and declares go 1.26.4 — verify only; no edit expected unless sync fails.
• Specify-phase artifacts already exist — verify and preserve; apply minimal fixes only when misaligned with spec.md (broken links, missing topics, .env in .gitignore).
• Git (implement-agent, before other changes): Per implement-change skill and go-storywriter 00001 pattern:
  • git init in go-dns/ if .git is missing.
  • Add remote origin → ssh://git@gitea.neitzel.de:2222/konrad/go-dns.git if absent.
  • Checkout branch feature/C-00001-setup-project.
  • Baseline commit (chore: baseline before change C-00001-setup-project) and git push -u origin feature/C-00001-setup-project.
  • Risk: Gitea repository konrad/go-dns may need to be created on the server before push succeeds; if push fails, stop and report — do not proceed until resolved.
• Go toolchain 1.26.4 available locally.
• No third-party Go dependencies for this change (no application .go files).

Implementation steps

Step 0 — Git workspace setup

Run from go-dns/ per Prerequisites. Establish the feature branch and baseline commit before creating or modifying scaffolding files in steps 1–11.

Step 1 — Verify Go module

1. Confirm go.mod exists with:
   • module gitea.neitzel.de/konrad/go-dns
   • go 1.26.4
2. No require block expected (no dependencies until a future library change).
3. Fix only if module path or Go version diverges from spec.

Step 2 — Verify workspace registration

1. From workspace root: confirm grep -q go-dns go.work.
2. Run go work sync from workspace root.
3. If sync fails, resolve go.mod issues from step 1 and retry.

Step 3 — Verify Cursor project rule

Confirm .cursor/rules/project-specification.mdc:

• Front matter: alwaysApply: true, short description for go-dns.
• Body: pointer to docs/project-specification.md as authoritative spec.
• Brief stack summary: Go library, module path, godns package at module root, BIND target, TSIG, AXFR-only transfer, typed RR builders (future), BIND testcontainer (future integration tests).
• Note that project .cursor overrides workspace defaults when they conflict.

Follow patterns from go-ollama/.cursor/rules/project-specification.mdc and log-analyzer/.cursor/rules/project-specification.mdc. Minimal edits only if topics are missing or contradict resolved decisions.

Step 4 — Verify project specification document

Confirm docs/project-specification.md (English) covers all required topics:

Section	Content
Overview	Library for RFC 2136 dynamic updates and AXFR zone transfer against BIND; TSIG auth; typed zone data and RR builders (future).
Module metadata	Path gitea.neitzel.de/konrad/go-dns, public package godns, Go 1.26.4, Gitea remote URL.
Target environment	BIND 9.x; UPDATE with automatic TCP fallback; AXFR over TCP; TSIG required; ASCII-only names in v1; no IXFR in v1.
Operation surface	Pointer to change 00001 spec.md as authoritative catalog (sections 1–10).
Zone data model	Logical types Record, RRSet, Zone, UpdateResult, TransferResult.
BIND configuration	Pointer to docs/bind-tsig-configuration.md (after step 8).
API style	Typed builders per RR type; no generic rdata string as primary API.
Change workflow	docs/changes/ efforts; backlog at docs/backlog.md.
Tests (future)	Unit go test ./...; integration go test -tags=integration ./... with BIND testcontainer — not implemented in this change.
Package layout (planned)	package godns at module root; internal/ for wire protocol (future).

After step 8, ensure the BIND section links to the live docs/bind-tsig-configuration.md path (not only “written during implementation”).

Step 5 — Preserve backlog

1. Confirm docs/backlog.md exists with a prioritized IXFR entry under Zone transfer (P2 per specify phase).
2. Do not recreate or substantially rewrite; minimal link fixes only if needed.

Step 6 — Verify .gitignore

Confirm exclusions for:

• Go binaries and test artifacts (*.test, *.out, project binary names)
• IDE/OS junk (.idea/, .vscode/, .DS_Store)
• Local secrets: testconfig/local.toml (already present); add .env / .env.* if missing per spec requirement 10

Step 7 — Verify project README

Confirm README.md (English):

• Describes library intent: dynamic updates (RFC 2136) and AXFR zone transfer
• States early setup status and links to docs/changes/00001-setup-project/spec.md
• Documents module path and godns import name
• Links to docs/project-specification.md and docs/backlog.md
• After step 8, add link to docs/bind-tsig-configuration.md

No build/run instructions for a binary (library-only; no cmd/ in this change).

Step 8 — Create BIND TSIG configuration guide

Create docs/bind-tsig-configuration.md (English). This is the primary new deliverable of this change. Content MUST satisfy spec section 9:

#	Requirement	Guide content
1	Define the key	key "name" { algorithm ...; secret "..."; }; in named.conf or included file. State explicitly that key generation is out of library scope; operators use tsig-keygen, rndc tsig-keygen, or secret management.
2	Zone ACLs	For zone "example.com" { ... }: allow-update { key "name"; }; and allow-transfer { key "name"; }; for the same TSIG key.
3	Stricter policy	Mention update-policy as optional supplement or alternative to broad allow-update.
4	Reload / validation	named-checkconf, rndc reload, verify with nsupdate -y and TSIG-signed AXFR (dig -y or equivalent).
5	Security notes	Restrict key to needed zones; do not expose AXFR publicly; separate read vs write keys when policy requires (library may use different keys per client).
6	Minimal example	Complete named.conf fragment: key block + zone block with allow-update and allow-transfer for one key (expand the illustrative fragment in spec section 9).

Suggested structure: introduction → key definition → zone configuration → optional update-policy → reload and verification → security → full example → related docs (link to spec.md, project-specification.md).

Step 9 — Cross-document alignment pass

After the BIND guide exists:

1. Update docs/project-specification.md BIND section with a direct link to bind-tsig-configuration.md.
2. Update README.md documentation links if not done in step 7.
3. Confirm .cursor/rules/project-specification.mdc still accurately references the guide path.
4. Re-read resolved decisions in spec.md — no contradictions (godns, typed builders deferred, AXFR-only, BIND testcontainer deferred, TCP fallback deferred, ASCII-only deferred, no key generation).

Step 10 — Change documentation layout

1. Confirm docs/changes/ exists.
2. This folder docs/changes/00001-setup-project/ contains spec.md (specify phase) and plan.md (plan phase).
3. verification.md and changes.md are out of scope for implement phase (verify-agent / document-agent).

Step 11 — Local verification (implement-agent quick check)

From workspace root and go-dns/:

cd /Users/konrad/Projects/go && go work sync
test -f go-dns/docs/bind-tsig-configuration.md

No go test or go build — no Go source in this change.

Files to create or modify

Path	Action	Purpose
.git/ + branch feature/C-00001-setup-project	create (implement-agent, step 0)	Git repo, remote, baseline push
go.mod	verify/preserve	Module identity and Go version (specify phase)
go.work (workspace root)	verify only	Already lists ./go-dns
.cursor/rules/project-specification.mdc	verify/preserve	Cursor always-on project rule
docs/project-specification.md	verify/modify	Authoritative project spec; link BIND guide after step 8
docs/backlog.md	verify/preserve	IXFR backlog entry
.gitignore	verify/modify	Go artifacts + secret paths (add .env if missing)
README.md	verify/modify	Project overview; link BIND guide after step 8
docs/bind-tsig-configuration.md	create	BIND allow-update / allow-transfer TSIG guide
docs/changes/00001-setup-project/spec.md	verify/preserve	Full operation catalog — do not rewrite
docs/changes/00001-setup-project/plan.md	create	This plan (plan phase)

Not created in this change: any *.go files, internal/, cmd/, unit tests, integration tests (*_integration_test.go), docker-compose.yml, frontend/, verification.md, changes.md.

Dependencies and risks

Risk	Mitigation
Gitea remote repo does not exist	Create konrad/go-dns on Gitea before baseline push; implement-agent stops on push failure
go work sync fails	Ensure valid go.mod before sync
Scope creep (RFC 2136, AXFR, TSIG code, testcontainers)	Strictly follow spec out-of-scope; documentation and scaffolding only
Rewriting spec.md operation catalog	Preserve specify-phase content; verify AC-6 only
BIND guide incomplete	Use spec section 9 checklist as implement-agent acceptance gate before handoff
Doc drift between README, project-spec, cursor rule	Step 9 alignment pass

External dependencies: None (no Go packages, no Docker for this change).

Integration tests: Not applicable in this change. Future library changes will use BIND testcontainer via testcontainers-go with build tag integration and command go test -tags=integration ./... (Docker required in CI) per workspace integration-testing.mdc and spec resolved decisions. Document in project-spec and cursor rule only — do not implement testcontainers or BIND image wiring here.

Future changes (out of scope, for traceability):

Topic	When
package godns public API and internal/ wire protocol	After setup verified
Typed RR builders (A, AAAA, MX, …)	Dedicated change
Zone data types in Go (Record, Zone, …)	With or after first protocol change
RFC 2136 UPDATE + automatic TCP fallback	Library implementation change
AXFR + TSIG signing	Library implementation change
BIND testcontainer integration tests	After minimal library surface exists
IXFR	Backlog P2 — docs/backlog.md

Test strategy

Criterion	Verification method
AC-1	From workspace root: grep -q go-dns /Users/konrad/Projects/go/go.work exits 0; cd /Users/konrad/Projects/go && go work sync exits 0
AC-2	grep -E '^module gitea.neitzel.de/konrad/go-dns$' /Users/konrad/Projects/go/go-dns/go.mod and grep -E '^go 1.26.4$' /Users/konrad/Projects/go/go-dns/go.mod
AC-3	test -f go-dns/.cursor/rules/project-specification.mdc; grep -q 'alwaysApply: true' go-dns/.cursor/rules/project-specification.mdc; grep -q 'docs/project-specification.md' go-dns/.cursor/rules/project-specification.mdc
AC-4	test -f go-dns/docs/project-specification.md; `rg -i 'gitea.neitzel.de/konrad/go-dns
AC-5	test -f go-dns/README.md; `rg -i 'update
AC-6	test -f go-dns/docs/changes/00001-setup-project/spec.md; manual/doc review — sections 1–10 present: session/auth, updates, prerequisites, RR types, update submission, AXFR (no IXFR as v1 feature), zone data model, auxiliary, BIND guide requirements, non-goals. Command aid: rg -n '^### [0-9]+\.' go-dns/docs/changes/00001-setup-project/spec.md shows numbered sections 1–10 under “DNS operations” and section 9 “BIND configuration” / section 10 “Explicit non-goals”
AC-7	(a) Spec requirement: `rg -i 'bind-tsig-configuration
AC-8	test -f go-dns/docs/backlog.md; rg -i 'IXFR' go-dns/docs/backlog.md
AC-9	test -f go-dns/docs/changes/00001-setup-project/spec.md; test -f go-dns/docs/changes/00001-setup-project/plan.md; after verify/document phases: verification.md and changes.md in same folder
AC-10	`rg -i 'godns

Integration test command: N/A for this change (BIND testcontainer deferred to a future change).

Unit test command: N/A — no Go source files; go test ./... has nothing to run until a later change adds packages.

Docker required: No (for this change).

Rollback notes

• Code/docs: Revert commits on feature/C-00001-setup-project or remove files created in this change; preserve docs/changes/ history if useful.
• Workspace: go.work entry for ./go-dns can remain (harmless) or be removed manually if fully abandoning the project.
• Remote: No destructive git operations; branch can be deleted on Gitea manually if the effort is cancelled after push.
• Runtime: No deployed services or containers for this change.