agctl 0.2.0__tar.gz → 0.3.0__tar.gz

agctl-0.3.0/.claude/agents/docs-watcher.md

@@ -0,0 +1,182 @@
+---
+name: docs-watcher
+description: Review code/config changes and keep all user-facing docs fresh — DESIGN.md (WHAT/WHY), ARCHITECTURE.md (HOW), and the consumer skills/ tree (operational CLI/config reference an agent follows).
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+---
+
+# docs-watcher Subagent
+
+You are the `docs-watcher` subagent for the `agctl` project. Your job is to review code and
+configuration changes, then decide which **user-facing markdown** needs updating to stay
+fresh against the as-built code.
+
+You own **three document families**, each at a different abstraction altitude. Preserving
+the altitude of each — and catching the case where code shipped but a family was forgotten —
+is your core responsibility. The mock-server feature shipped with DESIGN.md and
+ARCHITECTURE.md synced but the `skills/` tree stale; that gap is exactly what you exist to
+close.
+
+## The Documents and Their Altitudes
+
+### `docs/DESIGN.md`
+**Altitude:** WHAT and WHY — design-level, user-facing contract.
+
+Contains: goals/non-goals (§1); config schema — fields and meaning (§2); CLI command surface
+— flags, args, behavior (§3); output schema — JSON structure, error types (§4); config
+resolution order (§5); extension contracts (§9); roadmap/future work (§10).
+
+**What does NOT belong here:** implementation mechanics, module layouts, internal data flows.
+
+### `docs/ARCHITECTURE.md`
+**Altitude:** HOW — implementation-level, as-built source of truth.
+
+Contains: module & layer map (§3); request lifecycle (§4); config pipeline (§5); transport/
+client internals incl. lazy imports and exception mappings (§8); testing architecture (§12);
+design-vs-implementation deltas (§14).
+
+**What does NOT belong here:** user-facing behavior changes that are spec-level, not
+implementation-level.
+
+### `skills/` (consumer skills — agents copy these into their own repos)
+**Altitude:** OPERATIONAL — "what an agent needs to know to use agctl correctly **today**."
+
+- **`skills/agctl/SKILL.md`** — *driving* the CLI: the command surface, flags, the one-JSON-
+  object-per-invocation contract (and its streaming exceptions), exit-code meanings, output
+  parsing, gotchas, command forms, recipes, and lifecycle protocols. **Stale here = an agent
+  issues a wrong command, misreads output, or misses a gotcha.**
+- **`skills/agctl-config/SKILL.md` + `reference/*.md`** — *authoring* `agctl.yaml`: the config
+  contract (placeholder syntaxes, cross-refs, naming, verify-after), the mode table, the
+  structural checklist, and one `reference/<mode>.md` per section (http / kafka / db / db-write
+  / mock / init). **Stale here = an agent writes invalid config or misses a schema/validation
+  rule.**
+
+**What does NOT belong here:** design rationale (that's DESIGN) or internal mechanics
+(that's ARCHITECTURE). Skills state the *operational surface* — what to type, what comes
+back, what to watch for.
+
+## Mapping a Change to Documents
+
+A single change can land in several families. Update **every** family that applies, each at
+its own altitude:
+
+| Change | DESIGN.md | ARCHITECTURE.md | skills/agctl | skills/agctl-config |
+|---|---|---|---|---|
+| New/changed CLI command, flag, output shape, exit code, runtime behavior | §3 / §4 | §4 / §6 / §8 (if internal flow changes) | intent table, command forms, gotchas, recipes | — |
+| New/changed config field, validation rule, placeholder semantics | §2 | §5 (pipeline) / §15 (limitations) | gotchas (if user-facing) | SKILL.md contract + structural checklist + matching `reference/<mode>.md` |
+| New/changed `discover` category or item shape | §3 | — | discover section + category list | verify/discover notes |
+| Internal module layout, runtime flow, packaging, test seams | (only if user-visible) | §3 / §4 / §8 / §12 / §14 | — | — |
+| Pure refactor / test-only / cosmetic, no behavior change | — | — | — | — |
+
+**Overlaps are the rule, not the exception.** A new command usually touches DESIGN §3 **and**
+`skills/agctl`; a new config field usually touches DESIGN §2 **and** `skills/agctl-config`.
+The mock feature touched all four. When in doubt, check each family.
+
+## Your Decision Process
+
+For every code/config change, you MUST:
+
+1. **Read what changed** — `git status` and `git diff` (against the appropriate base) to see
+   what materially changed in behavior or structure.
+
+2. **Classify the change:**
+   - **(a) User-facing behavior/contract change** — new/changed CLI flags, config schema
+     fields, output schema, error types, extension contracts, discover surface.
+   - **(b) Internal structural/architectural change** — module layout, runtime flow, internal
+     mechanisms, packaging, testing architecture.
+   - **(c) Trivial/cosmetic/refactor-with-no-behavior-change** — test additions, formatting,
+     behavior-preserving refactors.
+
+3. **For each document family, ask:** does this change fall within this family's SCOPE **and**
+   ALTITUDE, **and** does it make the family's *current text* stale?
+   - DESIGN.md: user-facing contract changes (type a).
+   - ARCHITECTURE.md: internal structural changes (type b).
+   - skills/: the operational surface an agent relies on — usually the user-facing slice of
+     (a), occasionally the user-visible consequence of (b).
+
+4. **Decide:**
+   - If the change belongs in a family AT ITS ALTITUDE and is IMPORTANT → update it, matching
+     the file's existing style, terseness, and structure exactly. Edit only the relevant
+     lines/rows/bullets; do not expand or restructure the section.
+   - If the change has no home at this granularity, is trivial, or sits below the family's
+     altitude → **DO NOT update. A correct no-op is better than a speculative edit.**
+
+5. **Default to leaving docs untouched.** When unsure, do not edit — and say so.
+
+## Skills Freshness — Specific Rules
+
+These apply *in addition* to the general rules below:
+
+1. **Reflect AS-BUILT reality, never aspirational specs.** If a design spec said "discover
+   will surface X" but the code deferred it, the skill must say X is **not** surfaced. A skill
+   that claims a feature works when the code deferred it is a silent false green — the worst
+   failure mode for a test tool's docs.
+
+2. **State deferrals/limitations where an agent would otherwise assume support.** A behavior
+   the MVP doesn't cover must appear in the skill (gotcha, "not covered" note, or a
+   pointed-out absence) — not just in DESIGN §10. If `agctl discover` has no `mocks`
+   category, the skill says so.
+
+3. **Edit surgically and preserve structure.** Each skill file has a fixed shape — the mode
+   table, the numbered gotchas, the command-forms block, the recipes, the structural
+   checklist. Add a row / line / bullet / checklist item in the right slot; do not renumber,
+   reorder, or rewrite.
+
+4. **Keep cross-references intact.** The two skills point at each other (`agctl` ↔
+   `agctl-config`) and at `reference/<mode>.md` files. When you add a mode or command, wire
+   the cross-refs on both sides.
+
+5. **Watch for facts repeated across files.** Exit-code meanings, the placeholder-syntax
+   table, the `discover` category list, and "streaming commands" appear in more than one
+   place. If one copy changes, check the others. (When `mock run` became the second streaming
+   command, "http ping is the only streaming command" became wrong in `skills/agctl`.)
+
+6. **Skills are consumer artifacts, not repo internals.** They are copied verbatim into other
+   repos. Don't reference repo-internal paths, build commands, or test files from inside a
+   skill — only the `agctl` CLI surface and `agctl.yaml`.
+
+## Your Rules
+
+1. **NEVER change a document's altitude.** No implementation detail in DESIGN.md; no
+   operational how-to in ARCHITECTURE.md; no design rationale or internal mechanics in skills/.
+
+2. **NEVER invent new sections.** If a change has no natural home in an existing section, it
+   does not belong in that document.
+
+3. **Match existing style exactly.** Preserve each file's voice, terseness, table format, and
+   level of detail. Do not expand a section just because you can.
+
+4. **Reflect the code, not the spec.** Specs under `docs/superpowers/specs/` are historical
+   design records — never edit them, and never let them override what the code actually does.
+
+5. **Report transparently.** ALWAYS end by reporting:
+   - What you reviewed.
+   - What you changed (one-line reason per change, per family).
+   - What you deliberately did NOT change (and why) — including any family you checked and
+     found already fresh.
+
+6. **Git is your source of truth.** Use `git diff` to see what actually changed. Do not
+   speculate from file names alone.
+
+## Example Workflow
+
+1. `git status` → see which files changed.
+2. `git diff <base> -- <files>` → read the actual changes.
+3. Classify each change (a / b / c).
+4. For each family (DESIGN / ARCHITECTURE / skills-agctl / skills-agctl-config), ask the
+   scope+altitude+staleness question. Consult the mapping table above.
+5. When a skill is in scope, read the relevant skill file to see whether its current text is
+   now stale (don't assume — verify the claim against the code before editing).
+6. Make edits ONLY when the answer is "yes, at this altitude, important, and currently stale."
+7. Report your findings across all families.
+
+## What You Do NOT Do
+
+- Do NOT update docs for test additions or test-only changes.
+- Do NOT update docs for cosmetic refactorings (renames, formatting) that preserve behavior.
+- Do NOT update docs for internal helpers that aren't user-visible.
+- Do NOT "cover" a change by inventing a new section.
+- Do NOT touch archived specs under `docs/superpowers/specs/` — they are frozen history.
+- Do NOT sync the packaged `agctl/data/sample-config.yaml` to the README — that drift is
+  enforced by a test, not by you.
+- Do NOT silently edit — always report what you did and why, per family.

{agctl-0.2.0 → agctl-0.3.0}/.gitignore

@@ -23,3 +23,6 @@ venv/
 
 # UV package manager
 uv.lock
+
+# agctl test-runbook results (ephemeral per-run reports)
+*.results.md

agctl-0.3.0/.superpowers/sdd/hardening-report.md

@@ -0,0 +1,208 @@
+# Security Hardening: Redact Secrets from `ConnectionFailure` Detail in `connect()`
+
+## Summary
+
+Fixed a secret-leak finding from code review: `PostgreSQLDriver.connect()`
+emitted the raw connection config (including `password` and any URL-embedded
+credentials) into `ConnectionFailure.detail`, which `@envelope` writes to
+stdout — exposing secrets to the agent and any captured transcript.
+
+The fix adds a module-level `_redact_config` helper and applies it to the config
+copy that enters the error detail. The original config (used for the actual
+`psycopg.connect` call) is untouched.
+
+## The Leak (Before)
+
+`agctl/clients/db_drivers/postgresql.py` `connect()` raised:
+
+```python
+raise ConnectionFailure(
+    message=str(exc),
+    detail={"driver": "postgresql", "config": dict(config)},
+) from exc
+```
+
+`config` is the raw connection dict (`type/host/port/dbname/user/password/url`).
+`AgctlError.to_dict()` emits `detail` verbatim into the envelope's
+`error.detail`, which `@envelope` writes to stdout. So an auth/connection
+failure printed `error.detail.config.password` and any `user:pass@` segment
+inside `config.url` to stdout.
+
+The other `ConnectionFailure` raises in this file (`execute`/`execute_write`)
+pass only `message=str(exc)` with no `detail` — they do NOT leak. Only
+`connect()` needed the fix. (`describe_schema` does not exist on this driver.)
+
+## The Fix (After)
+
+Added `_redact_config(config: dict) -> dict` at module scope in
+`agctl/clients/db_drivers/postgresql.py`. It returns a **copy** with:
+
+1. **Secret-style keys** — any key whose name matches the substring pattern
+   `password|secret|token|key` (case-insensitive) — replaced by the fixed
+   sentinel `"***"`. This covers `password`, `key_password`, `api_token`,
+   `secret`, etc.
+2. **URL userinfo** — a `url` string value with a leading `user:pass@` (or
+   `user@`) userinfo prefix has that prefix replaced by `"***"`:
+   `postgres://u:p4ss@h:5432/db` -> `postgres://***@h:5432/db`. Handles both
+   `postgres://` and `postgresql://` schemes. URLs without userinfo, and
+   non-string `url` values, pass through unchanged.
+
+The original `config` is NOT mutated (the caller still needs the real values
+for the actual connection attempt / retry).
+
+Wired into `connect()`:
+
+```python
+detail={"driver": "postgresql", "config": _redact_config(config)},
+```
+
+Only `connect()` was touched. `execute` / `execute_write` were left as-is (they
+don't leak).
+
+## Helper's Home + Rationale
+
+**Location:** module-level function `_redact_config` in
+`agctl/clients/db_drivers/postgresql.py` (near its only caller).
+
+**Why not a shared util (`agctl/utils.py` / `agctl/_redact.py`)?**
+- No shared redaction util currently exists in the codebase (checked
+  `agctl/utils*`, `agctl/_*`, and grepped for `redact|sanitize|scrub` — no
+  hits).
+- The helper's only caller is this driver's `connect()`. Co-locating it keeps
+  the diff minimal and the logic next to the call site that needs it.
+- The Kafka leak check (below) found no other call site that puts secrets into
+  an error `detail`, so there is no second consumer to justify extraction.
+
+If a second leak surface appears later (e.g. a future driver copies this
+pattern), the helper can be promoted to a shared util at that point — the
+function signature (`dict -> dict`) is already general.
+
+## TDD Evidence
+
+### RED (failing test, before the fix)
+
+Command:
+```
+python3 -m pytest tests/unit/test_postgresql_driver.py::test_connect_failure_redacts_secrets_from_detail -q
+```
+
+Output (tail):
+```
+>       assert redacted_config["password"] == "***"
+E       AssertionError: assert 's3cret' == '***'
+E         
+E         - ***
+E         + s3cret
+tests/unit/test_postgresql_driver.py:312: AssertionError
+=========================== short test summary info ============================
+FAILED tests/unit/test_postgresql_driver.py::test_connect_failure_redacts_secrets_from_detail
+1 failed in 0.08s
+```
+
+### GREEN (after the fix)
+
+New test in isolation:
+```
+python3 -m pytest tests/unit/test_postgresql_driver.py::test_connect_failure_redacts_secrets_from_detail -q
+.                                                                        [100%]
+1 passed in 0.03s
+```
+
+Full driver file (confirms existing connection-failure tests still pass):
+```
+python3 -m pytest tests/unit/test_postgresql_driver.py -q
+.........................                                                [100%]
+25 passed in 0.04s
+```
+
+Full unit suite (no regressions):
+```
+python3 -m pytest tests/unit -q
+........................................................................ [ 14%]
+........................................................................ [ 28%]
+........................................................................ [ 42%]
+........................................................................ [ 57%]
+........................................................................ [ 71%]
+........................................................................ [ 85%]
+........................................................................ [100%]
+504 passed in 9.71s
+```
+
+Output is pristine (no warnings, no skips, no errors).
+
+The new test asserts:
+- `detail["config"]["password"] == "***"` (literal redaction).
+- `"s3cret" not in json.dumps(detail)` AND `"p4ss" not in json.dumps(detail)`
+  (strongest guarantee — covers url-embedded creds and any other secret-style
+  key).
+- `url` userinfo scrubbed (`"p4ss"` and `"u:p4ss@"` absent; `"host:5432"`
+  survives).
+- Non-secret keys (`type/host/port/dbname/user`) preserved unchanged.
+- Original caller config untouched (`config["password"] == "s3cret"` and
+  `config["url"]` still raw after the call — redaction operates on a copy).
+
+## Files Changed
+
+- `agctl/clients/db_drivers/postgresql.py`
+  - Added `import re`.
+  - Added module-level constants `_SECRET_KEY_PATTERN`, `_URL_USERINFO_PATTERN`,
+    `_REDACTED_SENTINEL`.
+  - Added module-level function `_redact_config(config: dict) -> dict`.
+  - Changed the `connect()` `ConnectionFailure` detail from
+    `dict(config)` to `_redact_config(config)`.
+- `tests/unit/test_postgresql_driver.py`
+  - Added `test_connect_failure_redacts_secrets_from_detail`.
+
+Diffstat: `2 files changed, 98 insertions(+), 1 deletion(-)`.
+
+## Kafka / Other-Driver Leak Check
+
+Scanned all `detail={...}` literals across `agctl/` and every
+`ConnectionFailure` raise in the Kafka client.
+
+**Result: none found.**
+
+- `agctl/clients/kafka_client.py` raises `ConnectionFailure(message=...)` with
+  NO `detail` dict at all (lines 154, 156, 160, 166-168, 399, 442-444, 447-449,
+  492, 509, 520, 527, 540). The only data embedded is broker addresses inside
+  the `message` string (e.g. line 443: `f"Kafka broker(s) {','.join(self._brokers)} unreachable: {exc}"`),
+  which are not secrets. `KafkaSSL.key_password` lives on the parsed config
+  object but is never placed into any error `detail`.
+- The only other `detail={...}` literals in the codebase
+  (`agctl/config/resolver.py:94` -> `{"field": last}` and
+  `agctl/commands/config_commands.py:204` -> `{"resource": ...}`) carry no
+  secrets.
+
+No follow-up items.
+
+## Self-Review
+
+- **COPY, not mutation:** `_redact_config` builds and returns a fresh dict; the
+  test explicitly asserts the caller's `config` is unchanged after the call.
+  The original `config` is still used verbatim for the `psycopg.connect` kwargs.
+- **Strongest-guarantee assertion holds for both secret carriers:** the test
+  asserts `"s3cret" not in json.dumps(detail)` (password) AND
+  `"p4ss" not in json.dumps(detail)` (url-embedded creds). Both hold.
+- **Non-secret keys preserved:** asserted for `type/host/port/dbname/user`.
+- **Existing connection-failure tests still pass:** the full driver file
+  (25 tests, including `test_connect_raises_connection_failure_on_operational_error`
+  and `test_connect_with_url_raises_connection_failure_on_psycopg_error`) is
+  green; the full unit suite (504 tests) is green.
+- **`execute`/`execute_write` untouched:** confirmed via the diff — the only
+  behavioral change is the one `detail=` line in `connect()`.
+
+## Concerns
+
+None.
+
+- The URL-userinfo regex (`^(postgres(?:ql)?://)[^@/]+@`) requires an `@`
+  before the first `/` to match, so URLs without userinfo pass through
+  unchanged. It handles `postgres://`, `postgresql://`, `user:pass@`, and
+  `user@` (no password) forms. A pathologically malformed URL with an
+  unencoded `@` inside the password (e.g. `postgres://u:p@ss@h/db`) would
+  under-redact the password portion — but such URLs are invalid (the `@`
+  must be percent-encoded) and not a realistic concern for this fix's scope.
+- The secret-key substring pattern matches `key`, which would also match a
+  hypothetical benign key like `keyboard_shortcut` — but no such key exists in
+  `DatabaseConnection`'s schema, and the broad match is intentional (the task
+  spec asks for substring match on `password|secret|token|key`).

agctl-0.3.0/.superpowers/sdd/progress.md

@@ -0,0 +1,50 @@
+# SDD Progress Ledger — db-schema-discovery
+
+Branch: feat/db-schema-discovery | Plan: docs/superpowers/plans/active/2026-07-04-db-schema-discovery.md
+
+Task 1: complete (commits 6388ab6..80ff01e, review clean — ✅ spec, Approved)
+Task 2: complete (commits 80ff01e..61f60a9, review clean — ✅ spec, Approved)
+  Minor (deferred to final review): push D6 system-schema/partition-leaf/relkind exclusions into SQL WHERE for the schema=None case (currently Python-only filter; correct + integration-tested, but pulls extra rows in production). Cosmetic: typo in task-2-report.md RED evidence path.
+  Note: Task 2 implementer self-invoked docs-watcher per CLAUDE.md (correct no-op, method unwired); not part of plan Task 2 but harmless.
+Task 3: complete (commits 61f60a9..062a2b7, review clean — ✅ spec, Approved; opus review verified all load-bearing rules in code)
+  Minor (deferred to final review):
+    M1: silent attnum-drop in constraint resolution (postgresql.py:287-303,321-325) could misalign positional pairing in inconsistent catalog — can't happen in practice (dropping a column drops its constraints); loud failure safer than quiet truncation.
+    M2: no ORDER BY on pg_constraint query (FK/unique order deterministic-by-chance; add ORDER BY con.oid for stable output).
+    M3: redundant Python schema re-check at postgresql.py:99-100 (dead defensive code).
+    M4: Any import verified present (not a defect).
+    M5 (WATCH-ITEM for Task 6): conkey/confkey consumed as Python lists; if psycopg3 returns int2vector as a string, a parser is needed. Integration test will surface it.
+Task 4: complete (commits 062a2b7..6877e76, review clean — ✅ spec, Approved; zero findings)
+Task 5: complete (commits 6877e76..0ab08be, review clean — ✅ spec, Approved; opus review verified probe-before-connect structurally guaranteed + disambiguation + verbatim hints)
+  Minor (deferred to final review):
+    M1: db_commands.py:202,214-222 use .get() on match fields (m.get("schema")/match.get("comment")) where brief specifies subscript (m["schema"]). Functionally equivalent for well-formed driver output; subscript would fail-loudly (KeyError) on a malformed driver contract instead of silently emitting null. Style/robustness, not load-bearing.
+Task 6: complete (commits 0ab08be..704335c, review clean — ✅ spec, Approved; live run PASS against Postgres 16 testcontainer)
+  M5 RETIRED: int2vector watch-item confirmed non-issue — psycopg3 returns conkey/confkey as Python int lists; live FK pairing assertions passed.
+  Minor (deferred to final review): redundant in-function `import json` at tests/integration/test_db_commands.py:60 (module already imports json).
+Task 7: complete (commits 704335c..e932d8d via fix, review Approved after fix — ✅ spec)
+  Fixed in-loop: I1 (DESIGN.md primary_key rendered as {name,columns} object but code returns list[str]; fixed to ["id"]; SKILL.md:142 preventive clarification primary_key→primary_key:[col]). Controller-verified the fix directly (surgical, reviewer-specified, sibling scan clean) — no full re-review subagent.
+  Minor (deferred to final review): ARCHITECTURE.md:100-102 lifecycle phrasing "close runs on raises" slightly imprecise (close runs before the raises, in _probe_and_describe's finally) — accurate, leave.
+
+ALL TASKS DONE. Branch tip = e932d8d.
+DEFERRED MINOR FINDINGS FOR FINAL REVIEW TRIAGE:
+  - T2/M1: push D6 system-schema/partition-leaf/relkind exclusions into SQL WHERE for schema=None (currently Python-only; correct + integration-tested, but pulls extra rows in production).
+  - T2/M(report): cosmetic typo in task-2-report.md RED evidence path.
+  - T3/M1: silent attnum-drop in constraint resolution (postgresql.py:287-303,321-325) could misalign positional pairing in inconsistent catalog — can't happen in practice; loud failure safer.
+  - T3/M2: no ORDER BY on pg_constraint query (FK/unique order deterministic-by-chance; add ORDER BY con.oid for stable output).
+  - T3/M3: redundant Python schema re-check at postgresql.py:99-100 (dead defensive code).
+  - T5/M1: db_commands.py:202,214-222 use .get() on match fields where brief specifies subscript; subscript would fail-loudly on malformed driver contract.
+  - T6/M1: redundant in-function `import json` at tests/integration/test_db_commands.py:60.
+  - T7/M1: ARCHITECTURE.md:100-102 lifecycle phrasing (imprecise, accurate).
+
+FINAL REVIEW: complete (93570b1..e932d8d). Verdict: Ready to merge — YES. Zero Critical/Important.
+  T3/M3 reclassified: NOT a trivial pre-merge cleanup. Fix subagent BLOCKED correctly — the Python schema re-check is load-bearing for the SQL-agnostic CatalogFakeCursor unit tests (scenarios 5/6 assert filtered results via it). Removing it needs a test-fixture refactor (fake honors n.nspname, or stage matching rows) → belongs in the follow-up cluster, not pre-merge. No commit made; tree clean.
+  Dropped (false premises): T6/M1 (file has no top-level import json — in-function is house style), T7/M1 (ARCH phrasing accurate).
+  FOLLOW-UP ISSUE (one cluster, touch postgresql.py once): T2/M1 push D6 filters into SQL WHERE (efficiency/defense-in-depth for schema=None on busy clusters) + T3/M3 delete dead Python re-check WITH CatalogFakeCursor fixture update + T3/M2 ORDER BY con.conname + T3/M1 loud attnum failure. Plus optional: T5/M1 .get()->subscript; multi-col FK in integration test.
+  Branch feat/db-schema-discovery tip = e932d8d. Merge-ready.
+
+4-REVIEWER PARALLEL CODE REVIEW (security / correctness / architecture / tests, all opus):
+  Security: YES. 1 Important (PRE-EXISTING, not in diff): connect() ConnectionFailure detail={"config": dict(config)} leaks password to stdout via envelope (postgresql.py:57-61). Reachable today via db query/assert/execute; db schema's ungated nature broadens surface. → recommend SEPARATE hardening PR (redact password/secret*/token*/*key in detail.config). New code clean (perfect bind-param discipline, no identifier construction, no new secrets, lifecycle correct).
+  Correctness: YES (empirically verified live vs Postgres 16, incl. composite FK positional pairing + identity-vs-serial redaction). 0 Critical/Important. 2 future-proofing notes: int2vector caveat (conkey is int2[] OID 1005 → list, correct; pg_index.indkey would be a string), pg_description query missing AND classoid='pg_class'::regclass (safe via global OID alloc).
+  Architecture: YES. 0 Critical/Important. 5 Minor nits: duplicated capability-refusal error construction (getattr vs _conn_dict['type']); double-probe on happy path (defense-in-depth); Python-side catalog filtering (T2/M1); probe asymmetry vs execute_write (intentional, document why); _probe_and_describe close-timing docstring (T7/M1).
+  Tests: WITH FIXES. 1 Important: schema-filter unit-test fidelity gap — CatalogFakeCursor is SQL-agnostic so unit tests can't catch a broken SQL WHERE; Python re-check masks it; integration test backstops only when Postgres available (self-skipping). SAME root as T3/M3 → one coherent fix (fake honors bind params + remove dead Python re-check). 6 Minor coverage-strength suggestions.
+
+AGGREGATE: 0 Critical across all 4. 2 Important (both pre-existing/follow-up, neither blocks this branch): password leak (separate PR), schema-filter fidelity (follow-up cluster already documented).

agctl-0.3.0/.superpowers/sdd/review-062a2b7..6877e76.diff

@@ -0,0 +1,165 @@
+# Review package: 062a2b7..6877e76
+
+## Commits
+6877e76 feat(db): add DbClient.supports_describe_schema + describe_schema probe
+
+## Files changed
+ agctl/clients/db_client.py   | 30 +++++++++++++++++++
+ tests/unit/test_db_client.py | 71 ++++++++++++++++++++++++++++++++++++++++++++
+ 2 files changed, 101 insertions(+)
+
+## Diff
+diff --git a/agctl/clients/db_client.py b/agctl/clients/db_client.py
+index b985315..56ef21e 100644
+--- a/agctl/clients/db_client.py
++++ b/agctl/clients/db_client.py
+@@ -100,12 +100,42 @@ class DbClient:
+             The dict returned by the driver's ``execute_write`` method.
+         """
+         execute_write_attr = getattr(self._driver, "execute_write", None)
+         if not callable(execute_write_attr):
+             raise ConfigError(
+                 f"connection's driver ({self._conn_dict['type']}) does not support writes",
+                 {"driver": self._conn_dict["type"]},
+             )
+         return self._driver.execute_write(sql, params)
+ 
++    def supports_describe_schema(self) -> bool:
++        """Return True if the driver offers a callable ``describe_schema``.
++
++        This is a **pre-connect**, side-effect-free probe: it does not call
++        ``describe_schema`` and does not require a connection. Callers
++        (``agctl db schema``) use it to fail fast when the selected driver
++        cannot introspect, without opening a connection.
++
++        Returns:
++            True if the driver has a callable ``describe_schema`` attribute.
++        """
++        return callable(getattr(self._driver, "describe_schema", None))
++
++    def describe_schema(self, table: str | None, schema: str | None) -> dict:
++        """Delegate to the driver's optional ``describe_schema`` capability.
++
++        Probes :meth:`supports_describe_schema`; raises ConfigError if the
++        driver lacks this optional capability. Otherwise delegates to the
++        driver and returns its dict unchanged.
++
++        Returns:
++            The dict returned by the driver's ``describe_schema`` method.
++        """
++        if not self.supports_describe_schema():
++            raise ConfigError(
++                f"connection's driver ({self._conn_dict['type']}) does not support schema discovery",
++                {"driver": self._conn_dict["type"]},
++            )
++        return self._driver.describe_schema(table, schema)
++
+     def close(self) -> None:
+         self._driver.close()
+diff --git a/tests/unit/test_db_client.py b/tests/unit/test_db_client.py
+index 9824992..03cfce3 100644
+--- a/tests/unit/test_db_client.py
++++ b/tests/unit/test_db_client.py
+@@ -40,20 +40,42 @@ class FakeDriverReadOnly(FakeDriver):
+ 
+ class FakeDriverWithNonCallableExecuteWrite(FakeDriver):
+     """Fake driver with non-callable execute_write attribute."""
+ 
+     def __init__(self):
+         super().__init__()
+         # Set execute_write to a non-callable value
+         self.execute_write = "not a method"
+ 
+ 
++class FakeDriverWithDescribeSchema(FakeDriver):
++    """Fake driver that supports schema discovery."""
++
++    SCHEMA = {
++        "tables": [
++            {"name": "users", "schema": "public", "columns": [{"name": "id"}]}
++        ]
++    }
++
++    def describe_schema(self, table, schema):
++        return self.SCHEMA
++
++
++class FakeDriverWithNonCallableDescribeSchema(FakeDriver):
++    """Fake driver with non-callable describe_schema attribute."""
++
++    def __init__(self):
++        super().__init__()
++        # Set describe_schema to a non-callable value
++        self.describe_schema = "not a method"
++
++
+ class FakeDriverSubclass(FakeDriver):
+     """Distinct class so tests can assert which driver was selected."""
+ 
+ 
+ class TestDbClientDirectInjection:
+     def test_execute_returns_driver_rows(self):
+         client = DbClient(
+             DatabaseConnection(type="postgresql", host="h"), driver=FakeDriver()
+         )
+         rows = client.execute("SELECT 1", {})
+@@ -162,10 +184,59 @@ class TestExecuteWrite:
+     def test_driver_with_non_callable_execute_write_raises_config_error(self):
+         """Driver with non-callable execute_write attribute: also raises ConfigError."""
+         client = DbClient(
+             DatabaseConnection(type="postgresql", host="h"),
+             driver=FakeDriverWithNonCallableExecuteWrite(),
+         )
+         with pytest.raises(ConfigError) as exc_info:
+             client.execute_write("INSERT INTO t (x) VALUES (1)", {"x": 1})
+         assert "does not support writes" in exc_info.value.message
+         assert exc_info.value.detail.get("driver") == "postgresql"
++
++
++class TestDescribeSchema:
++    """Tests for DbClient.supports_describe_schema + describe_schema probe."""
++
++    def test_driver_with_describe_schema_reports_support_and_delegates(self):
++        """Driver WITH callable describe_schema: probe True, delegation returns dict unchanged."""
++        client = DbClient(
++            DatabaseConnection(type="postgresql", host="h"),
++            driver=FakeDriverWithDescribeSchema(),
++        )
++        assert client.supports_describe_schema() is True
++        result = client.describe_schema(None, None)
++        assert result == FakeDriverWithDescribeSchema.SCHEMA
++
++    def test_driver_without_describe_schema_reports_no_support_and_raises(self):
++        """Driver WITHOUT describe_schema: probe False, raises ConfigError with driver type."""
++        client = DbClient(
++            DatabaseConnection(type="postgresql", host="h"),
++            driver=FakeDriverReadOnly(),
++        )
++        assert client.supports_describe_schema() is False
++        with pytest.raises(ConfigError) as exc_info:
++            client.describe_schema(None, None)
++        assert "does not support schema discovery" in exc_info.value.message
++        assert exc_info.value.detail.get("driver") == "postgresql"
++
++    def test_driver_with_non_callable_describe_schema_raises_config_error(self):
++        """Driver with non-callable describe_schema attribute: probe False, raises ConfigError."""
++        client = DbClient(
++            DatabaseConnection(type="postgresql", host="h"),
++            driver=FakeDriverWithNonCallableDescribeSchema(),
++        )
++        assert client.supports_describe_schema() is False
++        with pytest.raises(ConfigError) as exc_info:
++            client.describe_schema(None, None)
++        assert "does not support schema discovery" in exc_info.value.message
++        assert exc_info.value.detail.get("driver") == "postgresql"
++
++    def test_supports_describe_schema_does_not_open_connection(self):
++        """Pre-connect probe must be side-effect-free: no connection opened."""
++        fake = FakeDriverWithDescribeSchema()
++        client = DbClient(
++            DatabaseConnection(type="postgresql", host="h"),
++            driver=fake,
++        )
++        # Probe before any connect(); the driver must not have been connected.
++        assert client.supports_describe_schema() is True
++        assert fake.connected_with is None