diff --git a/docs/plans-executions/2026-09-16-1108-provider-docs-split.md b/docs/plans-executions/2026-09-16-1108-provider-docs-split.md index bbc56ab..c7a5f65 100644 --- a/docs/plans-executions/2026-09-16-1108-provider-docs-split.md +++ b/docs/plans-executions/2026-09-16-1108-provider-docs-split.md @@ -7,8 +7,8 @@ Plan: [docs/plans/2026-09-16-1108-provider-docs-split.md](../plans/2026-09-16-11 - [x] Step 2 — Write `docs/provider-spec-template.md` - [x] Step 3 — Write `docs/providers-existing.md` - [x] Step 4 — Rewrite `docs/providers.md` as the index; link edits -- [ ] Step 5 — Verification sweep -- [ ] Step 6 — Final summary, CHANGELOG after confirmation +- [x] Step 5 — Verification sweep +- [x] Step 6 — Final summary, CHANGELOG after confirmation ## Step 0 — Save and commit the plan @@ -140,3 +140,89 @@ updated to name the new files: The historical files under `docs/plans/` and `docs/plans-executions/` keep their `providers.md` links on purpose. + +## Step 5 — Verification sweep + +2026-09-16 11:45. All ten checks from the plan, run against the working tree +after Step 4; nothing needed fixing. + +Links (file targets and anchors) across the four new files plus `README.md`, +`CLAUDE.md` and `docs/architecture.md`, with anchors compared against +slugified headings of the target file: + +```sh +python3 - <<'PY' +import re, pathlib +files = ["docs/provider-contract.md","docs/provider-spec-template.md","docs/providers-existing.md","docs/providers.md","README.md","CLAUDE.md","docs/architecture.md"] +def slug(h): + h = re.sub(r'`','',h).strip().lower(); h = re.sub(r'[^\w\s-]','',h) + return re.sub(r'\s+','-',h).strip('-') +def headings(p): + return {slug(m.group(2)) for m in (re.match(r'^(#{1,6})\s+(.*)$', l) for l in open(p)) if m} +bad = 0 +for f in files: + for m in re.finditer(r'\]\(([^)\s]+)\)', open(f).read()): + t = m.group(1) + if t.startswith(('http://','https://','mailto:')): continue + path, _, anchor = t.partition('#') + target = pathlib.Path(f) if path == '' else pathlib.Path(f).parent/path + if not target.exists(): print(f, "missing", t); bad += 1; continue + if anchor and target.suffix == '.md' and anchor not in headings(target): print(f, "bad anchor", t); bad += 1 +print("link problems:", bad) +PY +``` + +Output: `link problems: 0`. + +Em-dashes, line references and the contract's abstractness: + +```sh +grep -n "—" docs/provider-contract.md docs/provider-spec-template.md docs/providers-existing.md docs/providers.md +git diff 2d959af -- README.md CLAUDE.md docs/architecture.md | grep '^+' | grep "—" +grep -nE '\.go:[0-9]+|:[0-9]+-[0-9]+' docs/provider-contract.md docs/provider-spec-template.md docs/providers-existing.md docs/providers.md +grep -niE "kubernetes|gcp|kvm|libvirt|squid|google|compute engine" docs/provider-contract.md +``` + +The only em-dash hit is the pre-existing "Leader-elected" cell of the +`architecture.md` components row, which shows as an added line because the +row's last cell was edited; no new em-dash was written. The other three +greps are empty. + +Nothing lost from the old blueprint's §9: the bold leads of every gap and +proposal bullet in `git show 0bb699b:docs/providers.md` were looked up in +the new files. The literal-prefix match reported 22 misses, all caused by +rewording ("isn't" to "is not", bold removed), so each topic was re-checked +by a distinctive phrase and all 22 are present in `providers-existing.md` +or contract §13. + +Paths and symbols: every `path/...` token in the four files exists except +the `config/samples/proxy_.yaml` pattern and the +`internal/provider/providertest` proposal; every backticked identifier in +the contract and template resolves in Go, Makefile or YAML sources except +file names, dotted `Type.method` forms, profile names and the `NewWith...` +placeholder. + +Axis alignment: the 19 axis codes from contract §4 each appear once as a +row in the appendix table (six cells per row) and at least once in the +template. + +`go build ./... && go test -short ./...`: all packages `ok`. + +## Step 6 — Final summary + +The split is complete on `feat/provider-blueprint`: five commits after the +plan commit, one per step. The CHANGELOG entry is deliberately not written +yet; per `CLAUDE.md` it is added once the user confirms the documents read +the way they want. Nothing has been pushed. + +Worth noting for whoever picks this up: + +- The contract's §4.20 table maps axis codes to template entry numbers; if + entries are renumbered, that column must follow. +- The `CHANGELOG.md` heading format in `CLAUDE.md` uses an em-dash; the + "no em-dashes" rule applied to the four new documents only. +- The stale `mock` comments in `internal/provider/provider.go`, + `internal/provider/registry/registry.go` and `api/v1alpha1/proxy_types.go` + are still listed as gaps, not fixed here. +- The next planned use of these files is a Proxmox provider: copy the + template to `docs/proxmox-provider-spec.md` and fill it in before any code.