docs(skills): rework the source-pack skill for the YAML pack era

The skill predated three structural changes that alter how a pack is
actually authored; the workflow now matches the shipped reality:

- Packs are embedded YAML assets: the implementation checklist authors
  packs/<provider>.yaml (bare table keys, derived ids, per-table
  pagination/columns/filters blocks, rationale as YAML comments) with a
  small OnceLock accessor module and registry entry — and enumerates
  what the validating loader already rejects (unknown keys, duplicate
  columns/mappings, undeclared filter columns, input-namespace
  collisions, zero page sizes, non-finite floats) so authoring
  attention goes to the semantic choices the loader cannot check.
- Fingerprint pinning gained the coverage-gap pin: the recipe now ends
  with fingerprint_uncovered_columns asserting each table's exact
  uncovered set, and the review checklist carries the item.
- Pagination soundness is a first-class phase-1 check: executors that
  filter rows AFTER paginating destroy the termination signal — the
  skill now teaches raw_page_size_path (with the upstream-contribution
  precedent, oomol-lab/open-connector#228) and the rule that a missing
  signal means upstream fix or deferral, never a heuristic.

The engine-baseline section is reframed (main carries the full baseline
today; verify-by-grep stays, with a refreshed marker list), and the
branch absorbed origin/main (one trivial doc-comment conflict on
fingerprint_schema, resolved keeping the richer rationale).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bakey

docs/superpowers/skills/source-pack/SKILL.md

@@ -91,7 +91,9 @@ before deciding anything. Summary of the rules that have survived review:
 ## Phase 3 — Implement
 
 Follow [references/implementation.md](references/implementation.md)
-§Implementation for the full checklist: pack file, registry entry, the
+§Implementation for the full checklist: the pack's YAML asset (packs are
+declarative embedded YAML validated by `packs/loader.rs` — authoring is
+data, not Rust) plus its accessor module and registry entry, the
 six fixture categories (including schema-mismatch), fingerprint pinning
 (capture → pin → sync test → contract-serving mocks → drift-refusal
 e2e), per-declaration end-to-end tests through `MockGateway`, and the
@@ -104,9 +106,9 @@ added `Fidelity` and list plucking; 5.2 added `total_pages_path`,
 (optional fields, `None` defaults) and test them at both the engine and
 the pack level. Before relying on any engine invariant this skill
 names, verify it exists on your base branch — see the implementation
-reference's **Engine baseline** section; a base predating milestone 5.2
-lacks the cursor/total safety guardrails entirely, and adding them is
-then prerequisite work.
+reference's **Engine baseline** section; `main` carries the full
+baseline today, but an older base may lack part of it, and adding the
+missing invariant (with regression tests) is then prerequisite work.
 
 ## Phase 4 — Self-review before any PR
 

docs/superpowers/skills/source-pack/references/contract-reconciliation.md

@@ -95,6 +95,17 @@ executors. This is the only reliable answer to:
   filter pushdown fidelity.
 - **Emitted output construction** — where the row array, totals, and
   cursors really live.
+- **Pagination soundness** — specifically whether the executor filters
+  rows AFTER paginating (`.filter(...)` on the fetched page). If it does,
+  the filtered page length carries no termination information and NO
+  pack-side termination rule is sound (a short page may be mid-collection;
+  an all-filtered page is empty but non-final). Check whether the
+  response carries a raw-length or total signal (`pageInfo.fetched`,
+  `paging.pages`) and declare it; if the gateway destroys the signal
+  entirely, the fix belongs UPSTREAM — contribute it (precedent:
+  oomol-lab/open-connector#228 added `pageInfo.fetched` to
+  `list_repository_issues`) or defer the table per the admission gate.
+  Never ship a table whose termination is known-unsound.
 
 ## 5. Validate generated inputs without provider credentials
 

docs/superpowers/skills/source-pack/references/implementation.md

@@ -2,29 +2,25 @@
 
 ## Engine baseline — verify before relying
 
-This guide references engine capabilities that landed with milestone 5.2
-(PR #172); a base branch that predates it lacks ALL of them. Before
-designing anything, verify your baseline:
+Everything this guide references now ships on `main`: embedded-YAML packs
+with the validating loader, fingerprint pinning, `total_pages_path` and
+`raw_page_size_path` on `PageNumber`, `PaginationCursorInvalid` /
+`PaginationRawPageSizeInvalid`, per-mapping `ValueFormat` (incl.
+`Verbatim`), `FieldType::TimestampSecondsUtc`, `FixedValue::StrList`,
+`SourcePackTable::error_path`, and `testutil::EnvVarGuard` +
+`fingerprint_uncovered_columns`. Still verify rather than assume — every
+safety invariant this guide names is a claim about code, and your base
+branch may predate one of them:
 
 ```bash
-git grep -l "PaginationCursorInvalid\|total_pages_path\|ValueFormat\|TimestampSecondsUtc\|EnvVarGuard" \
+git grep -l "raw_page_size_path\|PaginationCursorInvalid\|fingerprint_uncovered_columns" \
   crates/skardi/src/sources/providers/open_connector/
 ```
 
-Zero hits means the base still has the pre-5.2 engine, where — most
-dangerously — a non-string cursor and every row-path failure read as
-"scan complete": a drifted gateway truncates results silently. In that
-case, bringing the engine up to this baseline (with its regression
-tests) is a PREREQUISITE step of your milestone, not an assumption to
-inherit. More generally: every safety invariant this guide names is a
-claim about code — verify it exists (and its failure-mode test passes)
-on YOUR branch before leaning on it. Documentation snapshots go stale;
-`git grep` does not.
-
-The 5.2 baseline features referenced below: `total_pages_path` on
-`PageNumber`, `PaginationCursorInvalid`, per-mapping `ValueFormat`,
-`FieldType::TimestampSecondsUtc`, `FixedValue::StrList`,
-`SourcePackTable::error_path`, `testutil::EnvVarGuard`.
+Zero hits for any of these means your base predates part of the baseline;
+bringing the engine up to it (with its regression tests) is a
+PREREQUISITE step of your milestone, not an assumption to inherit.
+Documentation snapshots go stale; `git grep` does not.
 
 ## Design
 
@@ -56,6 +52,13 @@ Match the strategy to what the executor actually emits (phase 1):
   fails as `PaginationCursorInvalid`; a repeated cursor fails as
   `PaginationLoop`. Use the page size the provider recommends as its
   ceiling.
+- `raw_page_size_path` (mutually exclusive with `total_pages_path`): for
+  gateways that filter rows AFTER paginating and report the raw page
+  length (e.g. `$.pageInfo.fetched` on `github.list_repository_issues`,
+  upstream oomol-lab/open-connector#228). The scan continues while the
+  RAW page was full, no matter how short or empty the filtered rows are —
+  the filtered count carries no termination information for such actions,
+  and the heuristic would silently truncate.
 - The request page size doubles as the limit-pushdown ceiling — use the
   provider's maximum.
 
@@ -120,10 +123,23 @@ the gateway-failure path.
 
 Work module by module; the reference packs are the style guide.
 
-1. **`packs/<provider>.rs`** — table statics, a
-   `pub(crate) static <PROVIDER>_PACK: SourcePack`, registry entry in
-   `source_pack.rs` builtins (short-name uniqueness test will catch
-   collisions). Module doc records every design decision with rationale.
+1. **`packs/<provider>.yaml` + `packs/<provider>.rs`** — packs are
+   embedded YAML assets. Author the declaration in the YAML (`kind: pack`,
+   `pack:`, `version:`, `tables:` keyed by bare short names — the id is
+   derived as `<pack>.<table>`; per-table `action`, `row_path`,
+   `fingerprint`, `pagination`, `resources`, `fixed_inputs`, `columns`,
+   `filters`, `error_path`; design rationale as YAML comments). The `.rs`
+   module is a small accessor (`OnceLock` + `loader::builtin` +
+   `include_str!`) plus the module doc and the test suite; add the
+   registry entry in `source_pack.rs` builtins and a `mod` line in
+   `packs/mod.rs`. The loader validates structure FOR you at parse time —
+   unknown keys, duplicate columns, filters on undeclared columns,
+   duplicate mappings or shared filter inputs, resource/fixed-input/
+   pagination key collisions, zero page sizes, non-finite floats, and
+   path validity all fail as `SourcePackAssetInvalid` diagnostics — so
+   your authoring attention goes to the SEMANTIC choices the loader
+   cannot check: which action, which columns, which fidelity, which
+   termination signal.
 2. **Fixtures** (`packs/fixtures/<provider>/*.json`) — redacted,
    provider-shaped pages covering ALL SIX admission-gate categories:
    null-bearing, null-parent, empty-list/empty-page, nested,
@@ -146,7 +162,13 @@ Work module by module; the reference packs are the style guide.
      `<provider>_discovery(path)` helper), so every e2e registration
      exercises the gate's pass side;
    - one drift-refusal e2e: a stub serving a different schema must fail
-     registration with `ActionContractMismatch` naming table and action.
+     registration with `ActionContractMismatch` naming table and action;
+   - a coverage-gap pin: `testutil::fingerprint_uncovered_columns` walks
+     every mapped path through the captured row-item schema, and the pack
+     test asserts the exact uncovered set per table (columns riding
+     `additionalProperties` passthrough sit outside the fingerprint gate;
+     their drift surfaces at scan time). An empty set is the goal;
+     pinning a non-empty one makes the gap a reviewed fact.
 4. **End-to-end tests** via `MockGateway` (`testutil.rs` — use
    `envelope_ok` / `envelope_err` / `discovery_ok`; the mocks speak the
    real protocol: uniform envelope, `POST /v1/actions/:id`, camelCase).

docs/superpowers/skills/source-pack/references/review-checklist.md

@@ -15,11 +15,16 @@ The worst failure class: wrong results with a green status.
       end-of-collection spellings. Anything else that stops a scan —
       wrong-typed continuation state, structural traversal failure —
       fails loudly (`PaginationCursorInvalid`, `PaginationTotalInvalid`,
-      propagated row-path errors), never reads as "done". These
-      guardrails are the 5.2 engine baseline — VERIFY they exist on your
-      branch (implementation.md §Engine baseline); on a pre-5.2 base,
-      adding them (with regression tests) is prerequisite work, not a
-      checkbox to assume.
+      `PaginationRawPageSizeInvalid`, propagated row-path errors), never
+      reads as "done". VERIFY these guardrails exist on your branch
+      (implementation.md §Engine baseline); on an older base, adding them
+      (with regression tests) is prerequisite work, not a checkbox to
+      assume.
+- [ ] Post-pagination filtering checked: if the executor filters the
+      fetched page, the table declares `raw_page_size_path` (or an
+      authoritative total) — a filtered count is never a termination
+      signal, and a missing signal means upstream contribution or
+      deferral, not a heuristic.
 - [ ] Short/empty non-final pages cannot truncate: if the envelope has
       an authoritative total, the strategy declares `total_pages_path`;
       if not, the heuristic's limits are documented.
@@ -42,7 +47,9 @@ The worst failure class: wrong results with a green status.
       domain; every string-enum push is `Inexact`.
 - [ ] Fingerprints pinned from the live capture; sync test locks pin ↔
       contract fixture; drift-refusal e2e exists; mocks serve the
-      captured contracts so the gate's pass side actually runs.
+      captured contracts so the gate's pass side actually runs; the
+      fingerprint coverage gap (uncovered mapped columns) is pinned per
+      table.
 - [ ] Deliberate gaps (unmapped filters, deferred tables, `error_path:
       None`) each have a module-doc rationale AND a guard test.