feat: parity batch — Organizations async accounts, Cognito Identity STS creds, ID shapes, IoT MQTT jobs, SSM agent protocol, Backup restores

.agent/rules/dev-mcp.md

@@ -14,9 +14,9 @@ This repo ships a project-scoped `.mcp.json` at the root with three dev-only MCP
 
 On every new session in this repo:
 
-1. Run `make dev-mcp-check` (or `bash scripts/dev-mcp-check.sh --quiet`) and confirm the four CLIs (`gopls`, `mcp-language-server`, `terraform-mcp-server`, `npx`) are present.
-2. If anything is missing, run `make dev-mcp-install` once.
-3. If an MCP tool call fails mid-session, re-run `make dev-mcp-check` before falling back to raw `grep` / `find`.
+1. Run `task dev-mcp-check` (or `bash scripts/dev-mcp-check.sh --quiet`) and confirm the four CLIs (`gopls`, `mcp-language-server`, `terraform-mcp-server`, `npx`) are present.
+2. If anything is missing, run `task dev-mcp-install` once.
+3. If an MCP tool call fails mid-session, re-run `task dev-mcp-check` before falling back to raw `grep` / `find`.
 
 ## Optional: auto-check via SessionStart hook
 

.agent/rules/testing.md

@@ -8,7 +8,7 @@ trigger: always_on
 - Tests MUST be table tests. No matter what
 - Tests should always be parallel unless a environment variable is involved
 - Test should always cover at least 85% of the logic. 
-- `make test` to run all the unit tests
-- `make integration-test` to run all the int tests
+- `task test` to run all the unit tests
+- `task integration-test` to run all the int tests
 - use t.Context() in tests
 - never use t.Fatal or t.Error, only use require and asserts from testify

.agent/rules/workspace.md

@@ -2,7 +2,7 @@
 trigger: always_on
 ---
  - Tests MUST be table tests. No matter what
- - All code must pass `make lint`
+ - All code must pass `task lint`
  - Always run tests and lint before committing changes
  - Errors should be sentinel errors
  - logging must be via slog

.claude/skills/gopherstack-gates/SKILL.md

@@ -14,9 +14,15 @@ description: Pick the narrowest correct build/test/lint command for a gopherstac
 | Wire-shape confidence | `go test -race -run TestSDKCompleteness ./services/<svc>/...` plus that service's roundtrip tests |
 | Shared type in `pkgs/` changed | add `go build ./...` to the above — catches breaks in every consumer |
 | Anything touching persistence/snapshot | run that service's `persistence_test.go` explicitly |
-| Full gate before push | `make lint` → `make test` → `make build-linux` → `make integration-test`, in that order |
+| Full gate before push | `task lint` → `task test` → `task build-linux` → `task integration-test`, in that order |
 
-## Makefile targets
+## Iterative fix loops
+
+While fixing, use `scripts/dev/gotest-fail.sh [flags] <pkgs>` (e.g. `scripts/dev/gotest-fail.sh -run TestFoo ./services/sqs/...`).
+It runs `go test -json -race` and prints only failures: failed tests with output, build failures, package-level
+panics/races, and a summary. Exit code = go test's. Keep full `task test` for the final gate. If missing on your branch, it's in PR #2493 / main after merge.
+
+## Taskfile targets
 
 | target | runs | prereq |
 |---|---|---|
@@ -30,11 +36,11 @@ description: Pick the narrowest correct build/test/lint command for a gopherstac
 | `e2e-test` | `gotestsum ... -tags=e2e ./test/e2e/...` | `ui-build` |
 | `total-coverage` | unit+integration+terraform+e2e merged into coverage.out/.html | `build-linux` |
 | `docs` | `go run ./cmd/gendocs` — regenerates per-service README.md, root README table, `.badges/*.svg` | none |
-| `all` | `make lint-fix && make total-coverage` | — |
+| `all` | `task lint-fix && task total-coverage` | — |
 
-If you edit code and then run `make integration-test` without `make build-linux`
+If you edit code and then run `task integration-test` without `task build-linux`
 first, you are testing the OLD binary. Always rebuild first, or just run
-`make integration-test` (it depends on `build-linux` already) rather than
+`task integration-test` (it depends on `build-linux` already) rather than
 invoking gotestsum directly.
 
 ## golangci-lint gotchas that actually bite
@@ -44,7 +50,7 @@ routinely surprise agents:
 
 | gotcha | detail |
 |---|---|
-| `fieldalignment` | force-enabled via `settings.govet.enable: [fieldalignment]` on top of `enable-all: true`. Bites on every new struct. Fix: `fieldalignment -fix ./...` (also runs as part of `make lint-fix`), don't hand-reorder fields |
+| `fieldalignment` | force-enabled via `settings.govet.enable: [fieldalignment]` on top of `enable-all: true`. Bites on every new struct. Fix: `fieldalignment -fix ./...` (also runs as part of `task lint-fix`), don't hand-reorder fields |
 | golines, not `lll` | max line length is **120**, enforced by the `golines` formatter, not a linter check. Run `gofmt`/the formatter rather than manually wrapping |
 | `exhaustive` | fires on both `switch` AND `map` literals over enum-like types. A `default:` case satisfies it — add one instead of enumerating every case if the switch isn't meant to be exhaustive |
 | `mnd` (magic numbers) | bare numeric literals need a named const, even small ones in non-test files |
@@ -96,7 +102,7 @@ synctest.Test(t, func(t *testing.T) {
 
 (services/eks/async_lifecycle_test.go:35-58)
 
-`mulint` (declared as a go.mod `tool`, invoked separately by `make lint` via
+`mulint` (declared as a go.mod `tool`, invoked separately by `task lint` via
 `go vet -vettool=...`, NOT a golangci-lint plugin) catches mutex misuse —
 recursive locks, copied locks — relevant given the coarse-lock convention in
 `pkgs-catalog.md`.
@@ -114,5 +120,5 @@ names, `-timeout 10m`) → `terraform-tests`.
 Branch protection on `main`: 12 required contexts (lint, unit, e2e, ui-lint,
 ui-test, integration, terraform, modernize, govulncheck, build, CodeFactor,
 CodeQL), `enforce_admins=true`, no bypass. If your change doesn't pass
-locally with `make lint && make test && make build-linux &&
-make integration-test`, it will not pass CI either.
+locally with `task lint && task test && task build-linux &&
+task integration-test`, it will not pass CI either.

.claude/skills/gopherstack-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gopherstack-map
-description: Navigate the gopherstack repo (161 AWS service emulators under services/, plus pkgs/, cli.go, test/, ui/) without re-discovering structure via Glob/Grep every session. Use whenever asked to find where a service is registered, what operations it supports, its routing style, its parity grade, which pkgs/ package to reuse, or generally "where is X" / "how does service Y work" / "map this service" for any gopherstack service. Trigger before opening a service directory cold, and run scripts/svcmap.sh <service> for a compact structural summary instead of manually listing+grepping files.
+description: Navigate the gopherstack repo (161 AWS service emulators under services/, plus pkgs/, internal/app/cli.go, test/, ui/) without re-discovering structure via Glob/Grep every session. Use whenever asked to find where a service is registered, what operations it supports, its routing style, its parity grade, which pkgs/ package to reuse, or generally "where is X" / "how does service Y work" / "map this service" for any gopherstack service. Trigger before opening a service directory cold, and run scripts/svcmap.sh <service> for a compact structural summary instead of manually listing+grepping files.
 ---
 
 # gopherstack map
@@ -12,27 +12,31 @@ re-deriving it with Glob/Grep.
 
 | path | contents |
 |---|---|
+| `main.go` | thin entry (`func main` calls `app.Run()`); only other root files: `default.pgo` |
+| `internal/app/` | composition root (formerly package main): `cli.go` (`Run()`, service wiring) + `<x>.go` cross-service wiring files + white-box tests (`go test ./internal/app/`) |
+| `internal/routegates/` | route-gate logic (`gates.go`) + `path_gates.txt` |
+| `internal/cliconfig/` | lifecycle/persistable settings types shared with `internal/app` |
 | `services/<svc>/` | one emulator: `handler.go` + `store.go` + op-family files + `PARITY.md` + generated `README.md` |
 | `pkgs/` | 32 shared infra packages (table below) |
-| `cmd/gendocs` | regenerates per-service READMEs + `.badges/*.svg` from PARITY.md (`make docs`) |
+| `cmd/gendocs` | regenerates per-service READMEs + `.badges/*.svg` from PARITY.md (`task docs`) |
 | `test/e2e/` | SDK-driven e2e |
 | `test/integration/` | SDK-driven, Docker-container-backed — the real parity proof |
 | `test/terraform/` | terraform-provider-aws acceptance-style |
 | `ui/` | Svelte console source, `ui/src/routes/<service>/` |
 | `dashboard/static/spa/` | built UI output (gitignored but `.keep`-protected, load-bearing) |
 | `.beads/` | beads/Dolt issue tracker data |
-| `.badges/` | 5 committed SVGs regenerated by `make docs` |
+| `.badges/` | 5 committed SVGs regenerated by `task docs` |
 | `docs/` | hand-written narrative (architecture/, services/, docker.md, migration.md, quickstart.md) — distinct from generated per-service READMEs |
-| root `parity.md` | 1773-line live audit punch-list/planning doc — NOT a per-service manifest |
+| `docs/history/parity.md` | 1773-line live audit punch-list/planning doc — NOT a per-service manifest |
 | `services/_PARITY_TEMPLATE.md` | the PARITY.md schema |
 
 Also present: `internal/`, `modules/`, `proto/`, `examples/`, `bench/`, `scripts/`,
 `assets/`, `demo/`, `bin/` (build output).
 
 ## Entry points
 
-- `main.go` — 5 lines, calls `Run()`.
-- `cli.go` (~9160 lines): `Run()` at line 1747 (Kong CLI parsing, then service
+- `main.go` — 5 lines, calls `app.Run()`.
+- `internal/app/cli.go` (~9160 lines): `Run()` at line 1747 (Kong CLI parsing, then service
   wiring). `echo.New()` at 2110. `initializeServices` at 2628,
   `initIndependentServices` at 2660 — this is where every provider is
   constructed. Chaos middleware `registry.Use(chaos.Middleware(faultStore))`
@@ -46,7 +50,7 @@ Also present: `internal/`, `modules/`, `proto/`, `examples/`, `bench/`, `scripts
 
 | question | answer |
 |---|---|
-| Is service X registered, and how? | `cli.go`, `initIndependentServices` (2660) — grep the service name |
+| Is service X registered, and how? | `internal/app/cli.go`, `initIndependentServices` (2660) — grep the service name |
 | What ops does X support? | `GetSupportedOperations()` in `services/X/handler.go` |
 | What's X's parity status? | `services/X/PARITY.md` frontmatter, `overall: A|B` field |
 | What's X's wire shape for op Y? | `services/X/wire.go` — doc comment cites the SDK source line that confirms it |
@@ -73,7 +77,7 @@ Verified against grafana, networkmanager, account.
 | `wire_convert.go` | `toXWire`/`fromXWire` mappers |
 | `errors.go` | sentinel errors, `apiError` struct, constructors (`notFoundError`/`conflictError`/`validationError`/`quotaError`) |
 | `consts.go` | path-segment and JSON-key literals reused 3+ times (goconst-driven) |
-| `provider.go` | `Provider` implementing `service.Provider` (Name, Init) — what `cli.go` registers |
+| `provider.go` | `Provider` implementing `service.Provider` (Name, Init) — what `internal/app/cli.go` registers |
 | `persistence.go` | `backendSnapshot` struct + Snapshot/Restore |
 | `tags.go` / `handler_tags.go` | TagResource/UntagResource/ListTagsForResource/TaggedResources |
 | `cross_service.go` / `crossservice.go` | lazy sibling-service lookups |
@@ -149,3 +153,10 @@ service cold:
 ```bash
 .claude/skills/gopherstack-map/scripts/svcmap.sh grafana
 ```
+
+## scripts/dev/svcops.sh
+
+`scripts/dev/svcops.sh <service> [sdk-pkg]` diffs the pinned SDK's `api_op_*.go` against what
+`services/<svc>` routes: implemented / missing / unverified (dynamic names) / extra (not in SDK).
+Run it before claiming an op exists or is missing. Limit: "implemented" means routed, not a real
+backend; stubs are possible, read the backend method. If missing on your branch, it's in PR #2493 / main after merge.

.claude/skills/gopherstack-parity-audit/SKILL.md

@@ -23,7 +23,7 @@ description: Audit a gopherstack service for AWS parity and write or refresh its
    don't restate its recipes here.
 3. **Unit tests are not parity proof.** SDK-driven integration tests have
    caught 8 client-breaking wire bugs that green unit tests missed. Run
-   `make build-linux` before `go test ./test/integration/...` — integration
+   `task build-linux` before `go test ./test/integration/...` — integration
    tests exercise the real Docker-built binary, not a Go-level shortcut.
 4. **Grep-based stub hunting has false positives in both directions.** An op
    that returns an empty envelope *after* real backend logic ran is correct
@@ -117,7 +117,7 @@ audit tool being defeated, not satisfied.
 ## Regenerating docs
 
 ```bash
-make docs   # = go run ./cmd/gendocs
+task docs   # = go run ./cmd/gendocs
 ```
 Reads every `services/*/PARITY.md`, parses the frontmatter, and regenerates
 per-service `README.md`, the category-grouped table in root `README.md`, and
@@ -126,7 +126,7 @@ no shields.io, because a shields.io outage once broke every badge). Expect
 `README.md` + `.badges/*.svg` churn in your diff after editing any
 PARITY.md — that's expected, not a mistake to revert. The generator is
 idempotent: an identical PARITY.md corpus produces byte-identical SVGs, so if
-`make docs` produces no diff, nothing changed. `.badges/parity.svg` reflects
+`task docs` produces no diff, nothing changed. `.badges/parity.svg` reflects
 `gradeDistribution()` — a tally of `normalizeGrade(doc.Overall)` (strips a
 trailing `+`), e.g. "152 A".
 

.claude/skills/gopherstack-sdk-shape/SKILL.md

@@ -10,6 +10,8 @@ operation's own serializer/deserializer. Same-looking ops can differ: directconn
 `AllocatePrivateVirtualInterface` flattens `VirtualInterface` fields onto Output while
 `AllocateTransitVirtualInterface` nests it as `VirtualInterface *types.VirtualInterface`.
 
+For "which ops exist / are missing" use `scripts/dev/svcops.sh <service>` (see gopherstack-map).
+
 ## Fast path: use the script
 
 ```bash

.claude/skills/gopherstack-service-op/SKILL.md

@@ -5,6 +5,12 @@ description: Add a new AWS operation to an existing gopherstack service, or fini
 
 # gopherstack-service-op
 
+## Hard rule: shapes from the SDK, not memory
+
+Before writing any wire struct, field name, error code, or timestamp format, run the
+gopherstack-sdk-shape skill for that op and read its output. Run `scripts/dev/svcops.sh <svc>`
+before and after to confirm the op's status. If missing on your branch, it's in PR #2493 / main after merge.
+
 ## No-stub rule first
 
 Never ship a stub: no-op handlers, `&StubOutput{}`, fabricated IDs, or an op
@@ -29,7 +35,7 @@ pressure; check your own diff against it before calling the op done.
 | `wire_convert.go` | toXWire/fromXWire mappers |
 | `errors.go` | sentinel errors, `apiError` struct, constructors (notFoundError/conflictError/validationError/quotaError) |
 | `consts.go` | path-segment + JSON-key literals reused 3+ times |
-| `provider.go` | Provider implementing `service.Provider` (Name, Init) — what `cli.go` registers |
+| `provider.go` | Provider implementing `service.Provider` (Name, Init) — what `internal/app/cli.go` registers |
 | `persistence.go` | `backendSnapshot` struct + Snapshot/Restore |
 | `tags.go` / `handler_tags.go` | TagResource/UntagResource/ListTagsForResource/TaggedResources |
 | `cross_service.go` | lazy sibling-service lookups via a structurally-matched `siblingServices` interface |
@@ -149,7 +155,7 @@ If the resource is taggable, use the same `tags.Tags` field its other ops
 already use, created via `tags.New("<service>.<resource>.<id>.tags")`.
 `pkgs/tags` has its own internal locking, separate from `b.mu`.
 `handler_tags.go` is the thin HTTP wrapper; `TaggedResources()` feeds the
-resourcegroupstaggingapi cross-service integration (wired in `cli.go`, e.g.
+resourcegroupstaggingapi cross-service integration (wired in `internal/app/cli.go`, e.g.
 `wireTaggingGrafana`).
 
 ## Wire shapes

.claude/skills/gopherstack-session-close/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gopherstack-session-close
-description: Execute gopherstack's mandatory end-of-session close protocol completely and in order — file follow-up issues, run gates, close/update bd issues, then git pull --rebase, bd dolt push, git push, verify git status is clean. Use whenever a work session in this repo is ending, whenever asked to "wrap up", "close out", "finish this session", or before declaring work done. The single failure mode this exists to prevent is work that is committed but never pushed, or completed but never recorded in bd.
+description: Execute gopherstack's mandatory end-of-session close protocol completely and in order — file follow-up issues, run gates, close/update bd issues, then run task bd-audit, git pull --rebase, git push, verify git status is clean. Use whenever a work session in this repo is ending, whenever asked to "wrap up", "close out", "finish this session", or before declaring work done. The single failure mode this exists to prevent is work that is committed but never pushed, or completed but never recorded in bd.
 ---
 
 # gopherstack session close
@@ -30,9 +30,14 @@ bd create --title="<title>" --description="<desc>" --type=task --priority=<0-4>
 bd update <id> --claim        # if you're taking something on
 bd close <id> [--reason="<why>"]
 
-# 4. MANDATORY push sequence — do not stop partway
+# 4. Audit trailers on the branch, before the PR is squashed; reconcile any
+#    TRAILER MISMATCH / TYPO'D TRAILER ID findings
+task bd-audit
+
+# 5. MANDATORY push sequence — do not stop partway
+# Do NOT run `bd dolt push`: embedded Dolt, no remote, silently does nothing
 git pull --rebase
-bd dolt push
+git add .beads/issues.jsonl   # bd's auto-export hook usually does this
 git push
 git status                    # MUST show "up to date with origin"
 ```
@@ -48,7 +53,7 @@ else's problem (rebase conflict, stale branch, etc.) — resolve it.
 | Nothing (pure investigation/planning) | none — but still push any bd issue changes |
 | One service's Go code | `go test -race ./services/<svc>/...` |
 | Shared `pkgs/` code | `go build ./...` plus tests for every consumer you touched |
-| Anything you intend to open a PR from | full gate: `make lint && make test && make build-linux && make integration-test` |
+| Anything you intend to open a PR from | full gate: `task lint && task test && task build-linux && task integration-test` |
 
 See the `gopherstack-gates` skill for the full decision table and linter
 gotchas — don't re-derive it here.
@@ -71,7 +76,6 @@ gotchas — don't re-derive it here.
 | `bd remember "insight"` / `bd memories <keyword>` / `bd forget <key>` | persistent knowledge — use instead of MEMORY.md files |
 | `bd human <id>` | flag an issue for human decision |
 | `bd prime` | reload full bd context after compaction |
-| `bd dolt push` | push the Dolt-backed tracker DB to remote |
 
 Use `bd` for ALL task tracking in this repo — never TodoWrite, TaskCreate, or
 markdown TODO lists. Use `bd remember` instead of a MEMORY.md file.