vouchington-tooling 0.22.1 → 0.24.0

package/skills/pr-description/references/examples.md

@@ -0,0 +1,136 @@
+# Description examples
+
+These illustrative descriptions show how to keep conclusions visible while disclosing longer
+evidence. Use the consumer's actual headings, policy links, issue relationships, and run evidence.
+Do not copy a claim or figure unless the current change supports it.
+
+## Small behavior fix
+
+```markdown
+## Summary
+
+Reopening the review dialog now cancels its pending reset. Previously, the reset cleared the
+new selection because the timer outlived the closed state.
+
+## Impact
+
+Staff can close and reopen a review without losing the new selection. Closing normally still
+clears the old selection after the exit animation.
+```
+
+No diagram, cost calculation, database inventory, or local successful-test list is needed.
+
+## Database relationship change
+
+```markdown
+## Summary
+
+Recovery attempts now reference retained account identities through a foreign key. Previously,
+an unvalidated identifier could refer to an account that no longer existed.
+
+## Impact
+
+Operators can trace each attempt to a retained identity, and deletion cannot orphan recovery
+history. The API's recovery response is unchanged. Storage cost is unmeasured; retaining an
+identity row per deleted account adds storage proportional to account deletions.
+
+<details>
+<summary>Schema inventory and conformance</summary>
+
+| Object                                        | Before                  | After                             |
+| --------------------------------------------- | ----------------------- | --------------------------------- |
+| `account_identity` table                      | Absent                  | Retains each account's identity   |
+| `recovery_attempt.account_id` column          | Unvalidated UUID        | Removed                           |
+| `recovery_attempt.account_identity_id` column | Absent                  | Required foreign key              |
+| Foreign-key constraint                        | Absent                  | References `account_identity(id)` |
+| Lookup index                                  | Uses the removed column | Uses `account_identity_id`        |
+
+The relationship uses a typed column and concrete foreign key, as required by the repository's
+relational-storage policy. The current schema, recovery writer, account-deletion path, and
+operator query change together. There is no dual reader or writer.
+
+</details>
+```
+
+In a real description, link the consumer's policy and implementation evidence. Do not prescribe
+this consumer-specific retention or deployment policy for other repositories.
+
+## Workflow and cost change
+
+````markdown
+## Summary
+
+Test jobs now run once per revision. Previously, changing a pull request's draft status started
+a duplicate test run even though no test job consumed draft state.
+
+## Impact
+
+Contributors keep the checks already attached to their revision when marking it ready. Estimated
+runner use falls by one duplicate suite per draft-to-ready transition; the estimate assumes
+one transition and a 12-minute suite. Aggregate savings are unmeasured.
+
+<details>
+<summary>Before and after event flow</summary>
+
+```mermaid
+flowchart LR
+  subgraph Before
+    B1[Revision pushed] --> B3[Test suite]
+    B2[Draft marked ready] --> B4[Duplicate test suite]
+  end
+  subgraph After
+    A1[Revision pushed] --> A3[Test suite]
+    A2[Draft marked ready] --> A4[Merge eligibility only]
+  end
+```
+
+</details>
+````
+
+The diagram explains event ownership; a file list or arrows between the Summary and Impact sections
+would not clarify the behavior. Link the run measurements supporting a real estimate.
+
+## Harness gap: omitted local verification
+
+```markdown
+## Harness gaps
+
+CI found that the local pre-push command omitted the compiler-contract suite. The harness now
+includes that suite, and the missing public export is fixed.
+
+<details>
+<summary>Failure and durable correction</summary>
+
+The failed compiler-contract job on the first pushed revision reported the missing export.
+The pre-push record ran the component project only; the compiler-contract project was omitted
+because the command catalog did not include it. The catalog and pre-push selection now include
+the project, and a public-import regression covers this export.
+
+</details>
+```
+
+The actual record must link the failing run/job and exact head SHA, plus the local scope and
+correction evidence. Retain it when the corrected revision passes CI.
+
+## Harness gap: passed locally, failed in CI
+
+```markdown
+## Harness gaps
+
+The contract suite passed locally but failed in CI because the local runner selected the host
+architecture instead of the deployment target. Local validation now selects that target explicitly.
+
+<details>
+<summary>Local and CI scope difference</summary>
+
+The pre-push record and failing job used the same suite on the same revision. Their target
+configurations differed: local selected the host target, while CI compiled the deployment target.
+The local command now uses the deployment target, and a compiler regression covers the rejected
+cross-target import. This was a configuration mismatch, not an omitted suite.
+
+</details>
+```
+
+Link the concrete revision, failed job, local evidence, and correction in the actual record.
+An external service outage, unavailable CI-only credentials, or unknown local execution history
+does not support this claim. Explain such limitations separately when they affect the outcome.

package/skills/retrospective/SKILL.md

@@ -12,20 +12,31 @@ Local policy overrides these defaults; do not reload an already-read adapter or
 Use at task completion or session close-out when the repository has a retrospective workflow. Read
 local `AGENTS.md`, and journal guidance first.
 
-1. Check whether a retrospective already exists. Append only a material delta when local policy
-   says to append.
-2. Gather verifiable facts from the repository's approved status, validation, issue, and journal
-   sources. Do not estimate unknown facts from memory or transcripts.
-3. Summarize the outcome, plan-versus-actual differences, validation evidence, recurring friction,
-   and actionable process improvements. Keep one-off noise separate from a repeatable root cause.
-   Preserve each source entry's repository attribution when the journal supports it. A retrospective
-   that spans repositories names every represented repository.
-4. Save through the repository's required durable mechanism. Report the record identifier and any
-   follow-up decisions.
+1. Read the agent's own journal oldest-first and check for an existing retrospective. Capture a
+   material new observation before filing a follow-up issue. Preserve entry-level repository tags.
+2. Generate routine repository and transcript facts with the approved composer. Keep exact factual
+   section markers generated, preserve unavailable counts, and never replace missing evidence with
+   invented zero statistics. Do not paste raw collectors' output or manually reconstruct facts.
+3. Record work outcome, feedback coverage, and delivery independently. Success, failure,
+   cancellation, timeout, no-change, and policy refusal each need truthful terminal reporting.
+   Missing or truncated sources are unavailable/partial; durable interactive pending remains pending.
+   Autonomous completion requires the controller's acknowledged terminal readback or visible block.
+4. Report observed first-party tool and architectural behavior with concrete evidence and a
+   disposition, including useful resolved outcomes and rejected proposals. None observed requires
+   the inspected scope. Not assessed or unavailable requires a reason. Do not turn a plausible
+   cause into an observed diagnosis or infer permission decisions from requests.
+   For applicable configured tools, report used versus skipped/unavailable with reasons, the owning
+   workflow or command-catalog entrypoint, and terminal result/action, especially pr-shepherd and no-mistakes.
+5. Keep the top five findings or improvements in the human prose. The bounded durable evidence can
+   retain additional relevant findings; a prose limit is not permission to silently discard them.
+   Separate recurring root causes from one-off noise and preserve existing issue references.
+6. Save through the shared validated writer. Interactive outages use the approved bounded private
+   outbox with visible pending count; failed persistence blocks capture. Autonomous reporting stays
+   online and never uses that outbox to authorize an attempt or completion. Report the acknowledged
+   record/receipt, or the actual pending/blocked state and next replay action.
 
-Use raw evidence only for local verification. Save only bounded structured facts or redacted
-summaries in a durable retrospective; never embed unredacted logs, command output, environment
-dumps, provider payloads, or transcript content there.
-
-Consumer wrappers add transcript access, retention, a report schema, a journal provider, and issue
-filing policy. They cannot weaken this minimization boundary.
+Use raw evidence only for local verification. Save only bounded structured facts or redacted summaries
+in durable retrospectives; never embed unredacted logs, command output, environment dumps, provider
+payloads, or transcript content there. Exclude secrets. Consumer wrappers own providers, commands,
+report schema, retention, trusted runner mode, and issue routing; they cannot weaken this minimization
+boundary.

package/skills/retrospective-distill/SKILL.md

@@ -15,17 +15,26 @@ Use when completed retrospectives or journals should become durable follow-up wo
 1. Enumerate only completed, eligible session records. For repository-scoped work, filter sessions
    by repository membership and use only entries attributed to that repository. Leave untagged
    legacy records unclassified. Do not infer their repository. Leave in-progress sessions intact.
-2. Cluster findings by root cause. Prefer a few broad actionable themes over many narrow issues.
+2. 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,
+   dropped counts, requested versus observed outcomes, and useful resolved findings.
+3. 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.
-3. Verify each candidate against the current base. Search existing issues and open changes before
-   drafting. Skip work that is complete, explicitly rejected, or already covered.
-4. Draft self-contained issues with the problem, concrete proposed work, relevant areas, and
+4. Verify each candidate against the current base. Search existing issues and open changes before
+   drafting. Skip work that is complete, explicitly rejected, or already covered. A first-party version
+   bump is not proof of resolution: verify the adopted change against the original finding before
+   deferring. Capture a new observation in the journal before filing it.
+5. Draft self-contained issues with the problem, concrete proposed work, relevant areas, and
    validation. Route every authorized creation through
    [github-issue](../github-issue/SKILL.md), including its repository gate, label approval, and
    denied-external tracking behavior.
-5. Archive only records fully processed across every represented repository, under the repository's
+6. Archive only records fully processed across every represented repository, under the repository's
    retention rules. A one-repository pass leaves a multi-repository session active until the other
-   repositories are reviewed. Report created, updated, skipped, and deferred themes with reasons.
+   repositories are reviewed. Report reviewed, fixed, duplicate, deferred, quarantined, and
+   actionable dispositions with reasons. Keep the top five themes in human prose without dropping
+   underlying findings or unresolved records.
 
 Use source records only for local verification and leave them in the repository's approved journal
 or retention system. Public issue bodies contain only the minimum bounded facts or redacted

package/skills/review-ci-logs/SKILL.md

@@ -18,6 +18,11 @@ Use when investigating a CI failure, repeated workflow noise, or misleading diag
    failed steps and representative large entries, then remove the temporary artifacts.
 3. Classify each finding as a real error, misleading output, a downstream cascade, a necessary
    diagnostic, or a volume-only concern. Identify the first repository-owned root cause.
+   Compare the first failing run/job, its exact head revision, and scope with the pre-push verification record.
+   Establish whether the relevant local verification was omitted, passed under a different scope
+   or environment, genuinely CI-only, or unknown. A shared command name does not prove shared
+   project, target, fixtures, or configuration. Do not infer an omission from missing evidence or
+   label an external infrastructure failure a harness miss.
 4. For a persistent-workspace failure, name the producer of sparse state or unsafe ownership before
    proposing cleanup. Reject an unconditional pre-checkout workspace traversal. A compliant repair
    is the one in [github-actions-checklist](../github-actions-checklist/SKILL.md).
@@ -27,6 +32,11 @@ Use when investigating a CI failure, repeated workflow noise, or misleading diag
 6. Add focused regression evidence, run local workflow validation, and compare before and after
    output where that comparison is meaningful. Report deferred findings. Do not create issues unless
    authorized.
+7. Update [the PR description](../pr-description/SKILL.md) before handoff with confirmed omitted
+   verification or proven local/CI mismatch. Link the first failed run/job and its exact revision, the actual local
+   scope, the reason it missed the failure, and the durable harness correction or authorized
+   follow-up. Keep the distinction between omitted and locally passed checks explicit, and retain
+   confirmed gap records after CI turns green. Classify CI-only and unknown coverage separately.
 
 Consumer wrapper owns: workflow names, log retention, the CI provider command, retry policy, and
 scheduled automation.