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/`:

```bash
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|godns|BIND|RFC 2136|AXFR|TSIG|Record|RRSet|Zone|UpdateResult|TransferResult|bind-tsig-configuration' go-dns/docs/project-specification.md` returns matches for module path, BIND target, protocols, TSIG, zone model, and BIND guide reference |
| **AC-5** | `test -f go-dns/README.md`; `rg -i 'update|AXFR|gitea.neitzel.de/konrad/go-dns|godns|00001-setup-project/spec' go-dns/README.md` |
| **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|allow-update|allow-transfer' go-dns/docs/changes/00001-setup-project/spec.md` matches. **(b)** After implement: `test -f go-dns/docs/bind-tsig-configuration.md`; content checklist — `rg -i 'allow-update|allow-transfer|tsig-keygen|named-checkconf|rndc reload|update-policy|hmac-sha256' go-dns/docs/bind-tsig-configuration.md`; manual review confirms minimal `key` + `zone` `named.conf` example and security notes |
| **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|typed builder|AXFR|BIND testcontainer|TCP fallback|ASCII|git init' go-dns/docs/changes/00001-setup-project/spec.md` matches [Resolved decisions](#resolved-decisions) table |

**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.