vouchington-tooling 0.22.1 → 0.23.0

package/README.md

@@ -338,6 +338,32 @@ shape, including short table delimiters. `extractLooseMarkdownTableRows` is inte
 recovery for malformed pipe rows; callers supply table positions to exclude and retain ownership of
 their policy interpretation.
 
+`parseMarkdownSections` returns visible root H2 sections, their exact original `content`,
+`startOffset`/`endOffset` source ranges, heading line, and `hasVisibleContent`. Heading text is
+normalized by collapsing whitespace and removing Markdown formatting/comments and collapsed text; matching remains
+case-sensitive. Source offsets are JavaScript string offsets, so `source.slice(startOffset,
+endOffset)` preserves Unicode and CRLF exactly. Sections end at the next visible root H2 or EOF;
+fenced examples, quoted headings, and headings inside `<details>` do not create boundaries.
+
+```ts
+import { parseMarkdownSections, validateMarkdownSections } from 'vouchington-tooling/markdown'
+
+const document = parseMarkdownSections(body)
+const diagnostics = validateMarkdownSections(document, {
+  requiredHeadings: ['Summary', 'Impact'],
+})
+const relatedIssues = document.sections.find((section) => section.heading === 'Related issues')
+```
+
+The caller owns required headings. Validation returns diagnostics with `code`, `message`, and
+optional `heading`/`line`, for `missing-heading`, `duplicate-heading`, `empty-section`, or
+`malformed-details`. Nonempty visible paragraphs, lists, and populated table bodies satisfy the
+content check; comments, fenced/indented code, images, disclosure labels, and collapsed-only content
+do not. The parser tracks balanced nested details/summary tags in GFM HTML nodes, accepting optional
+summaries and quoted attributes; it is not a general HTML validator or sanitizer. It never rewrites
+the input or infers semantic relevance, cost, schema conformance, or failure causes. The existing
+`markdownSectionBetweenHeadings` API retains its original boundary behavior.
+
 `agent-harness-config` merges classifier-auto and sandbox keys into Claude, Codex, Grok, and Cursor
 config files. See [docs/agent-harness-config.md](./docs/agent-harness-config.md). `--global` updates
 home-directory configs; `--repo` updates a checkout. It does not copy allowlists, hooks, or plugins.

package/dist/markdown/details-scope.d.mts

@@ -0,0 +1,13 @@
+import type { MarkdownSectionsDiagnostic } from './document-types.mts';
+/** Tracks disclosure tags from HTML nodes, never from fenced code or Markdown comments. */
+export declare class DetailsScope {
+    private readonly markdown;
+    readonly diagnostics: MarkdownSectionsDiagnostic[];
+    private readonly frames;
+    constructor(markdown: string);
+    get visible(): boolean;
+    acceptHtml(html: string, startOffset: number): void;
+    finish(): void;
+    private acceptTag;
+    private problem;
+}

package/dist/markdown/details-scope.mjs

@@ -0,0 +1,73 @@
+/** Tracks disclosure tags from HTML nodes, never from fenced code or Markdown comments. */
+export class DetailsScope {
+    markdown;
+    diagnostics = [];
+    frames = [];
+    constructor(markdown) {
+        this.markdown = markdown;
+    }
+    get visible() {
+        return this.frames.length === 0;
+    }
+    acceptHtml(html, startOffset) {
+        const tokens = /<!--[\s\S]*?(?:-->|$)|<\/?[a-z][a-z\d:-]*(?:[^"'<>]|"[^"]*"|'[^']*')*>/giu;
+        for (const token of html.matchAll(tokens)) {
+            if (token[0].startsWith('<!--'))
+                continue;
+            const tag = /^<(\/?)([a-z][a-z\d:-]*)/iu.exec(token[0]);
+            const name = tag[2].toLowerCase();
+            if (name !== 'details' && name !== 'summary')
+                continue;
+            const line = this.markdown.slice(0, startOffset + token.index).split('\n').length;
+            if (/\/\s*>$/u.test(token[0])) {
+                this.problem(line, `${tag[2]} cannot be self-closing`);
+                continue;
+            }
+            this.acceptTag(name, tag[1] === '/', line);
+        }
+    }
+    finish() {
+        for (const frame of this.frames)
+            this.problem(frame.line, 'details has no closing tag');
+    }
+    acceptTag(name, closing, line) {
+        if (name === 'details') {
+            if (!closing) {
+                if (this.frames.at(-1)?.summary === 'open') {
+                    this.problem(line, 'details cannot open inside summary');
+                }
+                this.frames.push({ line, summary: 'absent' });
+                return;
+            }
+            const frame = this.frames.pop();
+            if (!frame)
+                this.problem(line, 'details closes without an opening tag');
+            else if (frame.summary === 'open')
+                this.problem(line, 'summary has no closing tag');
+            return;
+        }
+        const frame = this.frames.at(-1);
+        if (!frame) {
+            this.problem(line, 'summary must be inside details');
+            return;
+        }
+        if (closing) {
+            if (frame.summary !== 'open')
+                this.problem(line, 'summary closes without an opening tag');
+            else
+                frame.summary = 'closed';
+        }
+        else if (frame.summary !== 'absent') {
+            this.problem(line, 'details contains more than one summary or a nested summary');
+        }
+        else
+            frame.summary = 'open';
+    }
+    problem(line, reason) {
+        this.diagnostics.push({
+            code: 'malformed-details',
+            line,
+            message: `Malformed details: ${reason}.`,
+        });
+    }
+}

package/dist/markdown/document-sections.d.mts

@@ -0,0 +1,3 @@
+import type { MarkdownSectionsDocument } from './document-types.mts';
+/** Parses visible root H2 sections while retaining exact source ranges and disclosure scope. */
+export declare function parseMarkdownSections(markdown: string): MarkdownSectionsDocument;

package/dist/markdown/document-sections.mjs

@@ -0,0 +1,64 @@
+import { parseGfmMarkdown } from './ast.mjs';
+import { DetailsScope } from './details-scope.mjs';
+/** Parses visible root H2 sections while retaining exact source ranges and disclosure scope. */
+export function parseMarkdownSections(markdown) {
+    const sections = [];
+    const scope = new DetailsScope(markdown);
+    let current;
+    const visit = (node, collectText) => {
+        if (node.type === 'html') {
+            scope.acceptHtml(node.value, node.position.start.offset);
+            return;
+        }
+        if (node.type === 'code' || node.type === 'image')
+            return;
+        if (collectText &&
+            scope.visible &&
+            current &&
+            (node.type === 'text' || node.type === 'inlineCode') &&
+            node.value.trim()) {
+            current.hasVisibleContent = true;
+        }
+        if (!('children' in node))
+            return;
+        for (const [index, child] of node.children.entries()) {
+            visit(child, collectText && node.type !== 'heading' && (node.type !== 'table' || index > 0));
+        }
+    };
+    for (const node of parseGfmMarkdown(markdown).children) {
+        if (node.type === 'heading') {
+            const wasVisible = scope.visible;
+            const heading = headingText(node, scope).replace(/\s+/gu, ' ').trim();
+            if (node.depth === 2 && wasVisible && heading) {
+                if (current)
+                    current.endOffset = node.position.start.offset;
+                current = {
+                    heading,
+                    content: '',
+                    startOffset: node.position.end.offset,
+                    endOffset: markdown.length,
+                    line: node.position.start.line,
+                    hasVisibleContent: false,
+                };
+                sections.push(current);
+            }
+            continue;
+        }
+        visit(node, node.type === 'paragraph' || node.type === 'list' || node.type === 'table');
+    }
+    scope.finish();
+    for (const section of sections)
+        section.content = markdown.slice(section.startOffset, section.endOffset);
+    return { sections, diagnostics: scope.diagnostics };
+}
+function headingText(node, scope) {
+    if (node.type === 'html') {
+        scope.acceptHtml(node.value, node.position.start.offset);
+        return '';
+    }
+    if (node.type === 'text' || node.type === 'inlineCode')
+        return scope.visible ? node.value : '';
+    if (!('children' in node))
+        return '';
+    return node.children.map((child) => headingText(child, scope)).join('');
+}

package/dist/markdown/document-types.d.mts

@@ -0,0 +1,21 @@
+export type MarkdownVisibleSection = {
+    heading: string;
+    content: string;
+    startOffset: number;
+    endOffset: number;
+    line: number;
+    hasVisibleContent: boolean;
+};
+export type MarkdownSectionsDiagnostic = {
+    code: 'missing-heading' | 'duplicate-heading' | 'empty-section' | 'malformed-details';
+    message: string;
+    heading?: string;
+    line?: number;
+};
+export type MarkdownSectionsDocument = {
+    sections: MarkdownVisibleSection[];
+    diagnostics: MarkdownSectionsDiagnostic[];
+};
+export type ValidateMarkdownSectionsOptions = {
+    requiredHeadings: readonly string[];
+};

package/dist/markdown/document-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/markdown/index.d.mts

@@ -1,5 +1,8 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mts';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mts';
+export { parseMarkdownSections } from './document-sections.mts';
+export { validateMarkdownSections } from './validate-sections.mts';
+export type { MarkdownVisibleSection, MarkdownSectionsDiagnostic, MarkdownSectionsDocument, ValidateMarkdownSectionsOptions, } from './document-types.mts';
 export { markdownSectionBetweenHeadings } from './sections.mts';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mts';
 export { markdownNodeText } from './text.mts';

package/dist/markdown/index.mjs

@@ -1,5 +1,7 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mjs';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mjs';
+export { parseMarkdownSections } from './document-sections.mjs';
+export { validateMarkdownSections } from './validate-sections.mjs';
 export { markdownSectionBetweenHeadings } from './sections.mjs';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mjs';
 export { markdownNodeText } from './text.mjs';

package/dist/markdown/validate-sections.d.mts

@@ -0,0 +1,3 @@
+import type { MarkdownSectionsDiagnostic, MarkdownSectionsDocument, ValidateMarkdownSectionsOptions } from './document-types.mts';
+/** Validates caller-owned headings and visible core content without inferring semantic relevance. */
+export declare function validateMarkdownSections(document: MarkdownSectionsDocument, options: ValidateMarkdownSectionsOptions): MarkdownSectionsDiagnostic[];

package/dist/markdown/validate-sections.mjs

@@ -0,0 +1,34 @@
+/** Validates caller-owned headings and visible core content without inferring semantic relevance. */
+export function validateMarkdownSections(document, options) {
+    const diagnostics = [...document.diagnostics];
+    for (const heading of options.requiredHeadings) {
+        const sections = document.sections.filter((section) => section.heading === heading);
+        if (sections.length === 0) {
+            diagnostics.push({
+                code: 'missing-heading',
+                heading,
+                message: `Missing required section: ${heading}.`,
+            });
+            continue;
+        }
+        if (sections.length > 1) {
+            diagnostics.push({
+                code: 'duplicate-heading',
+                heading,
+                line: sections[1].line,
+                message: `Duplicate required section: ${heading}.`,
+            });
+        }
+        for (const section of sections) {
+            if (!section.hasVisibleContent) {
+                diagnostics.push({
+                    code: 'empty-section',
+                    heading,
+                    line: section.line,
+                    message: `Required section has no visible prose, list, or table content: ${heading}.`,
+                });
+            }
+        }
+    }
+    return diagnostics;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/agent-workflow/SKILL.md

@@ -13,6 +13,11 @@ Use before implementation. Inspect checkout status without discarding work; foll
 worktree, contribution, and CI policy. Read every applicable `AGENTS.md` from the repository root
 through changed files, plus relevant documentation and tests. Local instructions govern this skill.
 
+Use [PR descriptions](../pr-description/SKILL.md) before creating or updating a pull request.
+Diagnose failed CI with [CI-log review](../review-ci-logs/SKILL.md), then update confirmed harness
+gaps before handoff. Keep those records after checks pass; routine local successes stay in the
+evidence record.
+
 - During implementation, use [implementation](references/implementation.md).
 - Before handoff, use [evidence sweep](references/evidence-sweep.md).
 - For review, use [review](references/review.md).

package/skills/agent-workflow/references/review.md

@@ -5,3 +5,6 @@ contract compatibility, failure paths, authorization, untrusted input, secrets,
 boundaries. Remove dead paths and stale documentation rather than labeling them as legacy.
 
 Record unresolved risk as an explicit accepted decision or follow-up, never as an unnoticed gap.
+Check the pull-request description against the final behavior and audience impact. After CI
+diagnosis, ensure confirmed local-verification gaps or local/CI mismatches and their correction
+remain disclosed; passing checks do not erase the gap discovered earlier.

package/skills/manifest.json

@@ -4,9 +4,9 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "agent-workflow/SKILL.md",
-      "prerequisites": ["github-issue"]
+      "prerequisites": ["github-issue", "pr-description", "review-ci-logs"]
     },
     {
       "name": "backend-vitest-test-authoring",
@@ -18,13 +18,13 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "blackboard/SKILL.md"
     },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -38,26 +38,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -70,26 +70,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "planning/SKILL.md",
       "prerequisites": ["github-issue"]
     },
@@ -115,53 +115,53 @@
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "review-ci-logs/SKILL.md",
-      "prerequisites": ["github-actions-checklist"]
+      "prerequisites": ["github-actions-checklist", "pr-description"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.8.0",
+      "pluginVersion": "0.9.0",
       "path": "static-analysis-checklist/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },

package/skills/pr-description/SKILL.md

@@ -9,20 +9,54 @@ Read applicable `AGENTS.md` and their declared adapter alias, otherwise
 `.agents/skills/pr-description/SKILL.md` from the repository root if present.
 Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
 
-Use before opening or updating a pull request, or when reviewing PR hand-off quality. Read local
+Use before opening or updating a pull request, after diagnosing a CI failure, or at handoff. Read local
 `AGENTS.md`, pull-request template, and issue-linking policy first.
 
-Include enough context for a reviewer with no prior conversation:
+Keep the description understandable without the conversation. Its short visible core explains:
 
-- A concise summary of what changed and why.
-- The underlying root cause for a fix, not only its visible symptom.
-- Validation performed and any intentionally skipped checks with reasons.
-- Rollout, compatibility, operational safety, and follow-up context when the change affects a live
-  or independently deployed surface.
-- Correct issue relationships: close only issues fully resolved and explain any non-closing links.
-- A compact diagram only when it materially clarifies a multi-component flow or lifecycle.
+- **Summary:** what changed, why, and the concrete before/after behavior. For a fix, explain its
+  root cause as well as the symptom. A reader should understand the outcome before implementation
+  details.
+- **Impact:** who or what is affected and how their behavior changes. Name the actual audience,
+  such as end users, staff, API clients, operators, or contributors. Keep material risks and
+  limitations visible. For internal work, describe the affected development or operational flow.
 
-Use the repository's approved PR tooling and preserve sections managed by its review automation.
+Add detail only where the change warrants it:
+
+- For cost changes, state the direction and scope. Label figures as measured or estimated, name the
+  workload and assumptions, and link evidence. Say unmeasured when no defensible figure exists;
+  do not invent savings or claim a neutral cost without evidence. Follow the consumer's privacy
+  policy before reporting actual spending, and use approved aggregated or redacted evidence.
+- For database changes, inventory added, removed, and changed tables, columns, constraints, and
+  indexes. Explain the relationships and conformance to the consumer's schema rules, including
+  producer/consumer changes and any justified exceptions. Link the policy and concrete evidence.
+- For API, workflow, or independently deployed changes, explain the affected contract, lifecycle,
+  or operational safety. Follow the consumer's compatibility and deployment policy.
+- Use a before/after table or meaningful Mermaid diagram when it makes behavior, relationships,
+  workflow topology, or lifecycle easier to understand. Prose is sufficient for a simple change.
+
+Put long comparisons, inventories, diagrams, calculations, and failure evidence in collapsed
+`<details>` sections. Keep the short conclusions and material risks outside them. Keep the
+consumer's required visible core headings outside disclosure containers. Put opening/closing tags
+on separate lines, with a blank line after `</summary>` and before `</details>` so Markdown renders.
+Read [description examples](references/examples.md) when choosing a comparison, diagram, or failure
+record.
+
+Do not fill the description with routine local successful-test lists. This is a reporting rule,
+not permission to skip checks: execute required validation and retain its revision, exact scope,
+result, and any omission reason in the work's evidence record.
+
+Include **Harness gaps** only after CI diagnosis establishes an omitted local verification or a
+proven local/CI mismatch. Link the first failing run/job and its exact head revision, compare the actual local and
+CI scope, explain the omission or difference, and record the durable correction or authorized
+linked follow-up. Distinguish an omitted check from one that passed locally. Unknown coverage is
+not evidence of a miss; classify genuine CI-only or external infrastructure failures separately.
+Retain confirmed gap records after CI turns green. Diagnose the failure through the repository's
+CI investigation workflow; a failed status alone does not establish a gap.
+
+Use the repository's approved PR tooling and preserve sections managed by its review automation
+verbatim. Close only issues fully resolved and explain non-closing issue links. Apply this guidance
+to descriptions being created or updated, not a bulk rewrite of historical pull requests.
 
 Consumer wrapper owns: required headings, source-issue rule, merge policy, repository command, and
 hosted review system.

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/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.