vouchington-tooling 0.26.0 → 0.28.0

package/skills/postgres-schema-design/references/relations.md

@@ -0,0 +1,46 @@
+# Relations
+
+An identity that readers join is an FK column or an FK child row. JSON holds structured,
+schemaless data and history snapshots, including identities recorded as they were at the time.
+Do not use UUID arrays, JSON ids, or type/id pairs for live relations. A column never names a
+table: use one table per target and generate any per-relation progress enum from the same metadata.
+Cursor positions and random fencing tokens are intentionally not live entity references; record
+their reviewed exception instead of inventing a foreign key.
+
+Split tables when their columns or FK targets differ; share a table when only a value differs.
+Identical lookup values share a row without a source discriminator. Put subtype-only columns in
+a subtype table whose primary key also references the base row (`business_accounts.account_id`
+references `accounts.id`). A 1:N child remains an ordinary child table.
+
+For one of several sources, use an exclusive arc:
+
+```sql
+CHECK (num_nonnulls(order_id, invoice_id) = 1)
+```
+
+Both source columns have their own FK. If a reference must belong to the same account, enforce
+`FOREIGN KEY (account_id, invoice_id) REFERENCES invoices (account_id, id)` with a corresponding
+unique key on the target. A validation trigger is unnecessary. With nullable `invoice_id`,
+default `MATCH SIMPLE` skips that composite check when the reference is absent.
+
+A ledger that survives deletion references a retained identity row with explicit deletion
+behavior. Retained identities preserve history; they do not authorize operations on a deleted
+account, order, or invoice. Index FK columns with a leading key usable by referential checks.
+
+Finite code-defined values use enums. Use a lookup table when values carry attributes or arrive
+at runtime. Authenticated vendor-defined values are inserted into a shared lookup on first sight,
+with validation and concurrent insertion handled explicitly. Do not let untrusted strangers
+create unbounded permanent lookup rows; reviewed raw text can be appropriate for their input.
+Free text and a lookup's own natural key are not finite sets.
+
+Arrays are for enums or outside-defined lists; live identity collections use FK child rows,
+never `uuid[]`. User-submitted URLs go through one registry with centralized normalization and
+validation, then use URL FKs. Keep exact external protocol identifiers, capability URLs, and
+evidence snapshots unchanged when their contract requires it; document the exception.
+Do not duplicate a child collection into a parent column unless a trigger maintains the projection.
+
+Generic enforcement in `jonathanong/no-mistakes`: `postgres-column-naming`,
+`postgres-array-columns`, `postgres-table-shape`, `postgres-fk-index`, and
+`postgres-require-fk-on-delete`. These cover naming, configured shapes, and FK mechanics;
+inspect the installed rule versions and options rather than assuming complete semantic coverage.
+Comments and reviewed exceptions remain necessary.

package/skills/postgres-schema-design/references/table-shapes.md

@@ -0,0 +1,56 @@
+# Table shapes
+
+Choose a shape by lifecycle and meaning. Do not store hand-synchronized status beside lifecycle
+timestamps. A final lifecycle derives enum status with an immutable generated expression over
+timestamps such as `claimed_at`, `completed_at`, and `failed_at`. A time-based expiry needs an
+explicit sweeper-written timestamp; `now()` cannot appear in an immutable generated expression.
+When state keeps returning to earlier states, record append-only attempts or changes and derive
+current state from the latest row rather than erasing the previous lifecycle.
+
+| Concept                    | Shape                                                                                                                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Field-diff history         | `<entity>_revisions`: UUIDv7 `id`, entity FK, nullable revision actor FK with `ON DELETE SET NULL`, revision-type enum, `changes jsonb`.                                                   |
+| Typed lifecycle ledger     | `<entity>_changes`: UUIDv7 `id`, entity FK, change-type enum, retained actor identity FK with `ON DELETE RESTRICT`, typed joined payload and JSON for unjoined data. Time comes from `id`. |
+| Current state from a log   | Latest change by `id DESC`, projected through a shared trigger or read through a view.                                                                                                     |
+| Per-entity work            | `<entity>_<job>_work_items`: entity FK, lease and final-outcome columns, claim index, retention.                                                                                           |
+| Job progress               | `<job>_cursors`: finite enum key or checked singleton, keyset positions without FKs, optional sweep upper bound.                                                                           |
+| Inbound or protocol events | Append-only `<source>_events` with `occurred_at` recording the event's business time.                                                                                                      |
+
+Revisions and changes are append-only through a generic `fn_reject_mutation`, parameterized by
+actor columns that may be erased to NULL. Permit only those erasures; parent-cascade deletion
+may be permitted by policy. A trigger-depth test alone cannot prove a delete came from a parent
+cascade, because another trigger also increases depth. Do not copy the parent into each ledger
+row. Keep historical before/after snapshots as JSON rather than joined history child tables.
+A system change has a NULL actor. Retained actors remain historical identities, without authority.
+
+## Work leases
+
+The lease lives on a row that exists only for the work. If an invoice outlives a delivery job,
+use `invoice_delivery_work_items`, with an invoice FK and `ON DELETE CASCADE`, rather than putting
+the lease on the invoice. Do not create a shared polymorphic lease table.
+
+Use `lease_token uuid`, `leased_at`, `lease_expires_at`, `attempt_count`, `available_at`, and
+`completed_at` plus timestamps for final outcomes. Add `generation` only when re-enqueue can race
+a running worker. Each claim or reclaim gets a fresh opaque token. Every renewal, completion,
+and failure must include `WHERE lease_token = $mine`; zero affected rows means ownership was lost.
+Keep retries in an optional `_attempts` ledger with `attempt_number` when their lifecycle must
+survive. One-shot compare-and-set claims and human assignments need their own shapes.
+
+## Cursors and shared functions
+
+A cursor key names the finite thing being swept. A singleton uses
+`is_singleton boolean PRIMARY KEY DEFAULT true CHECK (is_singleton)`; the job seeds its own row
+with `ON CONFLICT DO NOTHING`. `cursor_<thing>_id` and optional `sweep_upper_bound_<thing>_id` are
+FK-free UUIDv7 positions; NULL means the start. Per-unit work progress belongs in work items.
+A UUIDv7 is assigned at insert, not commit: jobs that must see every committed row re-scan an
+overlap rather than assuming an id high-water mark proves commit order.
+
+Use `updated_at` only for mutable rows, always maintained by its trigger; application code never
+writes it. Comment every table, column, and view, including generated objects. Self-explanatory
+columns may have explicit reviewed local exceptions; view comments describe their reader boundary.
+Reuse generic trigger functions with `TG_ARGV` and `TG_TABLE_NAME`; quote dynamic identifiers
+with `format('%I', ...)`. A trigger function and a SQL-callable helper are separate functions.
+
+Generic enforcement in `jonathanong/no-mistakes`: `postgres-table-shape` and
+`postgres-duplicate-function-body`. Configure canonical shapes explicitly and verify which
+rules the installed release supports; lifecycle and authority decisions still need review.

package/skills/retrospective-distill/SKILL.md

@@ -17,11 +17,15 @@ Use when completed retrospectives or journals should become durable follow-up wo
    `data` fields, `dataArrayContains`, and `inactiveForHours`. It exports non-archived sessions to a
    private local file and returns the path, counts, checksum, and manifest, never the records.
    Before exporting, call `outbox_flush` and then `outbox_status` for every worktree that
-   `git worktree list` reports, passing each path as `worktree`, and stop if any still reports
-   pending records: an archived session refuses later delivery, so a retained record would never
-   be distilled. Outboxes in removed worktrees or on other machines cannot be drained this way, so
-   select with `inactiveForHours` to give them time to deliver. Leave in-progress sessions intact.
-   If the server is not connected, stop and report it; do not fall back to a CLI command.
+   `git worktree list` reports, passing each path as `worktree`, and stop if any reports a
+   `worktreePendingCount` above 0. Use the worktree count, never `pendingCount` or `status`, which
+   cover only the caller's own session: the sessions to distill belong to other agents, and an
+   archived session refuses later delivery, so a retained record would never be distilled. Outboxes
+   in removed worktrees or on other machines cannot be drained this way, so select with
+   `inactiveForHours` to give them time to deliver. Leave in-progress sessions intact. If a search
+   for `snapshot_export` (the tool names carry a harness prefix, see the
+   [blackboard skill](../blackboard/SKILL.md)) finds no server, stop and report it; do not fall back
+   to a CLI command.
 2. Before using any record, verify the file against the returned checksum, counts, and terminal
    manifest with the consumer's approved snapshot reader, and stop on a mismatch rather than
    treating missing records as absent. Read full records, with their storage type, repository
@@ -34,7 +38,8 @@ Use when completed retrospectives or journals should become durable follow-up wo
 3. Validate storage type and the shared envelope independently of optional category. Never repair
    unknown legacy types or repository provenance by inference. Quarantine malformed sessions with
    an explicit reason while processing valid unrelated sessions. Deduplicate at-least-once records
-   by exact session/source identity and reject conflicting duplicate content. Retain coverage,
+   by exact session/source identity and reject conflicting duplicate content. Records that differ
+   only in their server-assigned `timestamp` are one event. Retain coverage,
    dropped counts, requested versus observed outcomes, and useful resolved findings.
 4. Cluster findings by root cause. Prefer a few broad actionable themes over many narrow issues.
    Treat a finding already linked to an open tracker as context, not a duplicate.
@@ -47,8 +52,8 @@ Use when completed retrospectives or journals should become durable follow-up wo
    [github-issue](../github-issue/SKILL.md), including its repository gate, label approval, and
    denied-external tracking behavior.
 7. Archive only verified records fully processed across every represented repository, and never
-   while any worktree's `outbox_status` reports pending records, under the repository's retention
-   rules. Make one `session_archive` call per session, whose `sessionId` is the archived session,
+   while any worktree's `outbox_status` reports a `worktreePendingCount` above 0, under the
+   repository's retention rules. Make one `session_archive` call per session, whose `sessionId` is the archived session,
    not the caller. Immediately before each call, read that session with `journal_entries` and
    archive only if its entries match the verified snapshot's by source identity; otherwise leave it
    for the next pass, because an entry added after the export would never be distilled.