vouchington-tooling 0.22.1 → 0.24.0

package/dist/workflow-policy/permission-declarations.mjs

@@ -0,0 +1,55 @@
+export const PERMISSION_LEVEL_RANK = { none: 0, read: 1, write: 2 };
+const LEVELS_BY_SCOPE = {
+    actions: ['none', 'read', 'write'],
+    'artifact-metadata': ['none', 'read', 'write'],
+    attestations: ['none', 'read', 'write'],
+    checks: ['none', 'read', 'write'],
+    'code-quality': ['none', 'read', 'write'],
+    contents: ['none', 'read', 'write'],
+    deployments: ['none', 'read', 'write'],
+    discussions: ['none', 'read', 'write'],
+    'id-token': ['none', 'write'],
+    issues: ['none', 'read', 'write'],
+    models: ['none', 'read'],
+    packages: ['none', 'read', 'write'],
+    pages: ['none', 'read', 'write'],
+    'pull-requests': ['none', 'read', 'write'],
+    'repository-projects': ['none', 'read', 'write'],
+    'security-events': ['none', 'read', 'write'],
+    statuses: ['none', 'read', 'write'],
+    'vulnerability-alerts': ['none', 'read'],
+};
+export function isPlainRecord(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+export function isValidPermissionMap(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return Object.entries(value).every(([scope, level]) => {
+        const allowed = Object.hasOwn(LEVELS_BY_SCOPE, scope)
+            ? LEVELS_BY_SCOPE[scope]
+            : undefined;
+        return typeof level === 'string' && allowed?.includes(level) === true;
+    });
+}
+export function isValidDeclaration(value) {
+    return value === 'read-all' || isValidPermissionMap(value);
+}
+export function permissionMap(value) {
+    if (value === 'read-all') {
+        return new Map(Object.entries(LEVELS_BY_SCOPE)
+            .filter(([, levels]) => levels.includes('read'))
+            .map(([scope]) => [scope, 'read']));
+    }
+    return new Map(Object.entries(value).filter(([, level]) => level !== 'none'));
+}
+export function mergePermissionMaps(target, source) {
+    for (const [scope, level] of source) {
+        const current = target.get(scope) ?? 'none';
+        if (PERMISSION_LEVEL_RANK[level] > PERMISSION_LEVEL_RANK[current])
+            target.set(scope, level);
+    }
+}

package/dist/workflow-policy/permission-inheritance.d.mts

@@ -0,0 +1,8 @@
+import type { Workflow } from './permissions.mts';
+export declare function inheritanceAwarePermissionMismatches(args: {
+    callerPath: string;
+    callerJobKey: string;
+    callerWorkflow: Workflow;
+    calleePath: string;
+    calleeWorkflow: Workflow;
+}): string[];

package/dist/workflow-policy/permission-inheritance.mjs

@@ -0,0 +1,88 @@
+import { isPlainRecord, isValidDeclaration, isValidPermissionMap, mergePermissionMaps, permissionMap, PERMISSION_LEVEL_RANK, } from './permission-declarations.mjs';
+function sortedEntries(value) {
+    return [...value].toSorted(([left], [right]) => left.localeCompare(right));
+}
+function formatMap(value) {
+    return JSON.stringify(Object.fromEntries(sortedEntries(value)));
+}
+function diagnostic(callerPath, callerJobKey, calleePath, detail) {
+    return `  ${callerPath} job "${callerJobKey}" → ${calleePath}: ${detail}`;
+}
+export function inheritanceAwarePermissionMismatches(args) {
+    const prefix = (detail) => diagnostic(args.callerPath, args.callerJobKey, args.calleePath, detail);
+    const callerJob = args.callerWorkflow.jobs?.[args.callerJobKey];
+    const callerPermissions = callerJob?.permissions;
+    if (callerPermissions === 'write-all')
+        return [prefix('caller grants write-all')];
+    if (callerJob == null ||
+        !Object.hasOwn(callerJob, 'permissions') ||
+        !isValidPermissionMap(callerPermissions)) {
+        return [prefix('caller permissions must be an explicit map')];
+    }
+    const jobsPresent = Object.hasOwn(args.calleeWorkflow, 'jobs');
+    const jobsValue = args.calleeWorkflow.jobs;
+    if (jobsPresent && !isPlainRecord(jobsValue))
+        return [prefix('callee jobs are invalid')];
+    const calleeJobEntries = Object.entries(isPlainRecord(jobsValue) ? jobsValue : {});
+    const invalidJobKeys = [];
+    const calleeJobs = [];
+    for (const [key, job] of calleeJobEntries) {
+        if (isPlainRecord(job))
+            calleeJobs.push([key, job]);
+        else
+            invalidJobKeys.push(key);
+    }
+    if (invalidJobKeys.length > 0) {
+        return invalidJobKeys.map((key) => prefix(`callee job "${key}" is invalid`));
+    }
+    const topLevelPresent = Object.hasOwn(args.calleeWorkflow, 'permissions');
+    const topLevelPermissions = args.calleeWorkflow.permissions;
+    let validatedTopLevelPermissions;
+    if (topLevelPresent) {
+        if (topLevelPermissions === 'write-all')
+            return [prefix('callee requires write-all')];
+        if (!isValidDeclaration(topLevelPermissions)) {
+            return [prefix('callee top-level permissions are invalid')];
+        }
+        validatedTopLevelPermissions = topLevelPermissions;
+    }
+    if (calleeJobs.length === 0)
+        return [prefix('callee must declare at least one job')];
+    const invalidJobs = [];
+    const validatedJobPermissions = [];
+    let requiresWriteAll = false;
+    for (const [key, job] of calleeJobs) {
+        if (!Object.hasOwn(job, 'permissions'))
+            continue;
+        if (job.permissions === 'write-all') {
+            requiresWriteAll = true;
+        }
+        else if (isValidDeclaration(job.permissions)) {
+            validatedJobPermissions.push(job.permissions);
+        }
+        else {
+            invalidJobs.push(prefix(`callee job "${key}" permissions are invalid`));
+        }
+    }
+    if (invalidJobs.length > 0)
+        return invalidJobs;
+    if (requiresWriteAll)
+        return [prefix('callee requires write-all')];
+    const callerMap = permissionMap(callerPermissions);
+    const calleeMap = new Map();
+    if (validatedTopLevelPermissions !== undefined) {
+        mergePermissionMaps(calleeMap, permissionMap(validatedTopLevelPermissions));
+    }
+    for (const permissions of validatedJobPermissions) {
+        mergePermissionMaps(calleeMap, permissionMap(permissions));
+    }
+    const calleeFitsCaller = [...calleeMap].every(([scope, level]) => {
+        const callerLevel = callerMap.get(scope) ?? 'none';
+        return PERMISSION_LEVEL_RANK[callerLevel] >= PERMISSION_LEVEL_RANK[level];
+    });
+    const hasCallerInheritance = !topLevelPresent && calleeJobs.some(([, job]) => !Object.hasOwn(job, 'permissions'));
+    const permissionsMatch = JSON.stringify(sortedEntries(callerMap)) === JSON.stringify(sortedEntries(calleeMap));
+    if (calleeFitsCaller && (hasCallerInheritance || permissionsMatch))
+        return [];
+    return [prefix(`caller grants ${formatMap(callerMap)}, callee requires ${formatMap(calleeMap)}`)];
+}

package/dist/workflow-policy/permission-mismatches.d.mts

@@ -1,3 +1,6 @@
 import type { WorkflowTopology } from './types.mts';
 import { type Workflow } from './permissions.mts';
-export declare function callerCalleePermissionMismatches(topology: WorkflowTopology, documents: Readonly<Record<string, Workflow>>): string[];
+export type CallerCalleePermissionPolicy = {
+    comparison: 'exact' | 'inheritance-aware';
+};
+export declare function callerCalleePermissionMismatches(topology: WorkflowTopology, documents: Readonly<Record<string, Workflow>>, policy?: CallerCalleePermissionPolicy): string[];

package/dist/workflow-policy/permission-mismatches.mjs

@@ -1,4 +1,5 @@
 import { parsePermissions, permissionsToMap, requiredWorkflowPermissions, } from './permissions.mjs';
+import { inheritanceAwarePermissionMismatches } from './permission-inheritance.mjs';
 function formatPermissions(value) {
     if (value === null)
         return 'none';
@@ -6,7 +7,7 @@ function formatPermissions(value) {
         return value;
     return JSON.stringify(Object.fromEntries([...value].toSorted(([a], [b]) => a.localeCompare(b))));
 }
-export function callerCalleePermissionMismatches(topology, documents) {
+export function callerCalleePermissionMismatches(topology, documents, policy = { comparison: 'exact' }) {
     const mismatches = [];
     const jobsById = new Map(topology.jobs.map((job) => [job.id, job]));
     const workflowsById = new Map(topology.workflows.map((workflow) => [workflow.id, workflow]));
@@ -22,14 +23,24 @@ export function callerCalleePermissionMismatches(topology, documents) {
         if (!caller)
             throw new Error(`missing workflow document: ${callerPath}`);
         const job = caller.jobs?.[callerJob.key];
-        if (!job)
+        if (policy.comparison === 'exact' && !job)
             continue;
         const calleePath = callee.path;
         const calleeWorkflow = documents[calleePath];
         if (!calleeWorkflow)
             throw new Error(`missing workflow document: ${calleePath}`);
+        if (policy.comparison === 'inheritance-aware') {
+            mismatches.push(...inheritanceAwarePermissionMismatches({
+                callerPath,
+                callerJobKey: callerJob.key,
+                callerWorkflow: caller,
+                calleePath,
+                calleeWorkflow,
+            }));
+            continue;
+        }
         const calleePerms = requiredWorkflowPermissions(calleeWorkflow);
-        const jobPerms = parsePermissions(job.permissions);
+        const jobPerms = parsePermissions(job?.permissions);
         if (jobPerms == null) {
             mismatches.push(`  ${callerPath} job "${callerJob.key}" → ${calleePath}: missing explicit job-level permissions`);
             continue;

package/docs/workflow-and-compiler.md

@@ -37,7 +37,24 @@ const guardCoversConsumer = conditionEntails('always()', 'failure()')
 
 The permission comparison expects documents for every local caller and callable callee in the
 topology. The consumer reads workflow files and decides which inventory entries are provisioned;
-these functions never fetch secret values. Readiness checks rely on the parser's
+these functions never fetch secret values. The two-argument permission comparison requires exact
+caller/callee grants for compatibility. Consumers that intentionally let a reusable workflow job
+inherit the caller's token can opt into the fail-closed inheritance policy:
+
+```ts
+callerCalleePermissionMismatches(topology, documents, {
+  comparison: 'inheritance-aware',
+})
+```
+
+This mode requires an explicit caller permission map, rejects malformed declarations and
+`write-all`, and permits extra caller grants only when the callee omits top-level permissions and
+at least one callee job omits its own permissions. Explicit grants from every callee job still form
+required minima that must fit within the caller grants, including jobs guarded by `if`. The strict
+scope model follows GitHub's
+[workflow permission syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions).
+
+Readiness checks rely on the parser's
 `secretReferences` at workflow, job, and step scope. A missing required secret is considered ready
 only when a preceding guarded `run` step binds it to an env var, checks that var for emptiness,
 and exits with status 1. Optional `workflow_call` secrets are exempt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.22.1",
+  "version": "0.24.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/blackboard/SKILL.md

@@ -13,18 +13,38 @@ Use when the current repository provides a journal, blackboard, or equivalent du
 record. Read local `AGENTS.md` for the provider, credential, retention, and
 subagent-identity rules.
 
-1. Append a concise note when a check fails, permission is denied, scope changes, a repeated fix is
-   needed, or a tool result reveals a reusable gap. Include the finding, affected paths, concrete
-   evidence, and any tracking reference.
-2. Preserve the provider's required session and parent-session identity.
-   - Do not invent, guess, print, search for, or persist a credential outside its documented
-     mechanism.
-   - When the provider supports repository metadata, keep the cumulative canonical repository list
-     on that agent's own session. Tag each entry with only the repositories relevant to it.
-   - Update session metadata before appending. Stop if that update fails.
-3. If the journal service cannot authenticate or persist a mandatory entry, stop and report the
-   blocker rather than silently substituting a local file or memory.
-4. Read journal entries oldest-first when preparing a retrospective or clustering follow-ups; use
-   direct evidence rather than reconstructing events from memory.
+1. Capture consequential observations before filing an issue: failed or recovered checks, denied or
+   approved permissions, repeated fixes, scope changes, first-party tool behavior, and architectural
+   findings. Record useful resolved outcomes as well as unresolved gaps. Include bounded evidence,
+   affected areas, an explicit disposition, and an existing tracking reference when present.
+   Journal meaningful skips or bypasses of applicable configured workflows before completion, with
+   the owning workflow or command-catalog entrypoint, reason, and observed result/action.
+2. Use the shared validated envelope with storage `type: journal` or `retrospective`, canonical exact
+   entry repositories, stable `sourceEventId`, work outcome, and explicit feedback coverage. Category
+   is optional context; it never changes storage type or distillation eligibility. Generate routine
+   facts and metadata through the approved composer instead of hand-authoring factual markers.
+3. Preserve exact provider session and parent identities. Each agent writes only its own session.
+   Update that session's cumulative repository union before appending; never infer another repository
+   from prose or create a child identity from a model guess.
+4. Select the repository's trusted mode explicitly. Interactive outages may retain validated,
+   sanitized feedback in the bounded durable outbox. Report pending count and delivery state, replay
+   with the same source identity, and continue primary work only after persistence succeeds. A full,
+   unsafe, or unwritable outbox blocks capture; never evict or silently discard an unsent record.
+5. Autonomous runners require online session ensure, a fresh admission write, and readback before
+   launching an attempt. Terminal reporting preserves work outcome separately from feedback
+   coverage and delivery. A filesystem outbox never grants admission or acknowledged completion.
+6. Use at-least-once delivery with consumer deduplication by exact session/source identity. A
+   transport timeout can leave a late durable write; pending or blocked is never an acknowledged
+   receipt. Replay verifies matching content before retrying and rejects conflicting source reuse.
+7. Read journal entries oldest-first for retrospectives. Record explicit none-observed with inspected
+   scope, or not-assessed/unavailable with reason, when evidence does not establish a finding. A
+   permission request is not proof of approval or denial; localhost refusal is not proof of sandbox
+   enforcement. Mark partial capture and dropped counts instead of reporting clean evidence.
 
-Consumer wrapper owns: service, command, note grammar, archival policy, and issue destination.
+Never search for, print, invent, or mint credentials. Durable entries and outbox records contain only
+bounded structured facts or sanitized summaries, never raw command output, transcript content,
+environment dumps, provider payloads, or secrets. Known-secret redaction supplements the author's
+minimization responsibility; it cannot prove arbitrary prose contains no undisclosed secret.
+
+Consumer wrappers own service configuration, trusted mode selection, commands, outbox location,
+issue routing, and archival authorization.

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.