@1aboveio/skills 1.0.5 → 1.0.6

package/skills/risk-compliance/report-writing/SKILL.md

@@ -1,220 +0,0 @@
----
-name: report-writing
-description: "Convert compliance audit findings into audience-formatted reports. Four styles: VARS Review Report (Visa's official 2025 template, required verbatim for VARS engagements), Audit Report (compliance team), External Assessment (regulators/external auditors), Management Report (board/C-suite). Use whenever audit output needs to become a deliverable, even just 'write up the findings'."
-release-version: 0.42.0
----
-**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
-# Report Writing
-
-Generate compliance reports from structured audit findings. Four report styles target
-different audiences — same data, different depth and tone.
-
-## Input Format
-
-Structured findings in Markdown with per-item:
-- **Status:** Pass / Fail / Partial / N/A
-- **Severity:** Critical / Major / Minor / Observation
-- **Category:** e.g., Access Control, Data Protection, Incident Response
-- **Observations:** What was found
-- **Evidence:** Logs, configs, screenshots, code references
-- **Recommendations:** Suggested remediation
-
-If the input deviates, normalize it to the above structure before generating the report.
-
-### VARS-specific input requirement
-
-The VARS Review Report must be generated from the **full** per-control assessment —
-typically the `tracker.md` produced by the `compliance-audit` skill running against the
-VARS checklist (`skills/compliance/compliance-audit/references/vars-checklist.md`, or a
-parsed equivalent from `reg-parser`). Do **not** start a VARS report from a summary,
-verbal findings, or a partial sub-domain review — Visa's report aggregates a complete
-control-by-control assessment, and Section 5 of the deliverable explicitly references
-the *VARS Control Testing and Remediation Tracking* spreadsheet (which is the same
-tracker, in Visa's Excel format).
-
-If the user asks for a VARS report and you don't see a complete tracker covering all
-nine sub-domains, **stop and ask** for it — or offer to run `compliance-audit` first.
-A VARS report without the underlying control-level evidence is not a deliverable Visa
-will accept.
-
-## Report Style Selection
-
-| Style | Audience | When to use |
-|---|---|---|
-| **VARS Review Report** | Visa, acquirer leadership | Visa Acceptance Risk Standards engagements — uses Visa's official 2025 template |
-| **Audit Report** | Compliance team, internal auditors | Day-to-day remediation tracking, technical deep-dives |
-| **External Assessment** | Regulators, external auditors, certification bodies | Formal submissions, certification audits, regulatory filings |
-| **Management Report** | C-suite, board, leadership | Quarterly reviews, risk committee briefings, budget justification |
-
-Select the style based on the stated audience or purpose. If unclear, ask. Default to
-Audit Report when the requestor is technical. **If the framework is VARS / Visa
-Acceptance Risk Standards, always use the VARS Review Report style** — Visa requires
-its template verbatim.
-
-## Workflow
-
-### 1. Ingest Findings
-
-1. Read the audit findings file (Markdown). For VARS, this is the `compliance-audit`
-   tracker produced against the VARS checklist — it must cover all nine sub-domains.
-2. Parse each finding into: ID, title, category, status, severity, observations, evidence, recommendations.
-3. Validate completeness — flag any finding missing severity or status. For VARS,
-   additionally verify every sub-domain is represented; if any are missing, stop and
-   surface the gap to the user before drafting.
-
-### 2. Select Style
-
-Confirm the target style with the user or infer from context:
-- "VARS" / "Visa Acceptance Risk Standards" / "for Visa" → **VARS Review Report**
-- "for the regulator" → External Assessment
-- "for the board" / "executive summary" → Management Report
-- "full technical report" / default → Audit Report
-
-### 3. Generate Report
-
-**House style.** Use the nearest `WRITING.md`: start in the findings file's folder (pasted text: the output
-folder, else the working directory), then parents up to the repository root; never the home
-directory or above. Rate every issue from the evidence first; the style changes
-wording, never a rating, a finding or which issues appear. Then write the prose in its voice,
-language, terms, sentences and presentation. Keep the template structure, severity and rating scales
-(including Status values such as Pass / Fail / Partial), finding IDs and every input count; its
-terms apply to prose, not rating values. The request beats WRITING.md, which beats this skill's
-wording. Never edit WRITING.md. Bilingual: `write-doc`'s bilingual mode. No WRITING.md: write as
-below.
-
-The VARS Review Report ignores WRITING.md entirely: Visa's template wording and structure stay
-verbatim.
-
-Follow the style-specific template. Reference files provide the full structure:
-
-- **VARS Review Report:** Read `references/vars-report-template.md` (Visa's official 2025 template)
-- **Audit Report:** Read `references/audit-report-template.md`
-- **External Assessment:** Read `references/external-assessment-template.md`
-- **Management Report:** Read `references/management-report-template.md`
-
-### 4. Review and Finalize
-
-1. Verify coverage:
-   - Audit Report: every finding from the input has its own section.
-   - External Assessment: every finding is mapped to a regulatory requirement.
-   - Management Report / VARS: findings are aggregated by category/sub-domain with no category dropped.
-2. Confirm severity counts match the input data. For VARS: Section 3.d is **executive**
-   (a headline plus a 2–3 sentence business posture per sub-domain, no operational
-   detail); Section 4 is **department-manager** detail, with "Compliance Status" carrying
-   the tracker's Control Effectiveness Rating (Satisfactory / Improvement Recommended /
-   Unsatisfactory / N/A; worst rating across the row) and "Findings and Comments" written
-   as an inline observed → finding → comments narrative in the report's own words (no
-   source-document/clause/sample citations — those stay in the tracker) with the Actions
-   Required / Recommendations reproduced verbatim. When the ATPA archetype is in scope,
-   confirm all TPA controls are consolidated into a single "Third Party Agent" row rather
-   than scattered across the AACQ sub-domains.
-3. Check that no placeholder text remains (e.g. `{{...}}`, `____`, `MM/YEAR`).
-4. Output as Markdown. If DOCX is requested (the VARS deliverable is typically distributed as
-   DOCX to match Visa's template), **do not rely on a plain `pandoc` Markdown→DOCX conversion
-   for the Section 4 table** — pandoc collapses the `<br>` line breaks inside the wide
-   Findings-and-Comments cells, so the enumerated Actions Required / Recommendations items run
-   together and appear to be missing. Instead render the DOCX so each cell's `<br>`-separated
-   lines become **separate paragraphs** (e.g. build it with `python-docx`, or post-process the
-   pandoc output). In Section 4 specifically:
-   - split every `<br>` into its own paragraph in the cell, so each Actions Required /
-     Recommendations item is on its own visible line;
-   - render `**…**` labels (`Actions Required:`, `Recommendations:`) as real **bold**, not
-     literal asterisks;
-   - shade the **Compliance Status** cell by rating (Satisfactory = green, Improvement
-     Recommended = amber, Unsatisfactory = red, N/A = grey);
-   - set the page to **landscape** to give the table room.
-   For PDF, the same line-break requirement applies.
-
----
-
-## Style Summaries
-
-### VARS Review Report
-
-Visa's official 2025 template, used verbatim. Six fixed sections with mandated
-boilerplate (Purpose paragraph, reliance statement, recommendation summary stem) and
-nine fixed sub-domains in canonical order — plus a consolidated **Third Party Agent**
-row when the ATPA archetype is in scope. Detailed per-control findings live in the
-companion *VARS Control Testing and Remediation Tracking* Excel — the report itself
-aggregates one row per sub-domain. The two summary layers serve different audiences:
-**Section 3.d is executive** (business posture, 2–3 sentences per sub-domain) and
-**Section 4 is for department managers / control owners** (an inline observed → finding
-→ comments narrative in the report's own words, with verbatim Actions Required /
-Recommendations and no duplication of the tracker's evidence citations).
-
-**Key sections:** Cover, Document History, Distribution List, Executive Summary
-(Purpose / Background / VARS Control Assessment / Summary of Findings / Recommendation
-Summary), Observations Overview (sub-domain table), Detailed Information (pointer to
-Excel tracker), Next Steps.
-
-**Tone:** Formal, third-person, Visa-facing. Preserve the boilerplate paragraphs
-verbatim — paraphrasing breaks reviewer expectations.
-
-### Audit Report
-
-Full technical detail. Every finding gets its own section with evidence, root cause analysis,
-remediation steps, priority, and suggested timeline. Appendices contain raw evidence.
-
-**Key sections:**
-1. Report metadata (scope, period, assessor, framework)
-2. Executive summary (pass/fail counts)
-3. Findings (one per item — full detail)
-4. Remediation plan (prioritized)
-5. Appendices (evidence, methodology, glossary)
-
-**Tone:** Technical, precise, neutral. Use passive voice sparingly. Reference specific
-controls, configurations, and code paths.
-
-### External Assessment
-
-Formal language suitable for regulatory submission. Organized by regulatory requirement,
-not by internal finding ID. Includes gap analysis matrix and attestation-ready statements.
-
-**Key sections:**
-1. Cover page and scope statement
-2. Assessment methodology
-3. Compliance status by requirement (article/section mapping)
-4. Gap analysis matrix (requirement × status × severity)
-5. Remediation roadmap
-6. Attestation statement
-7. Appendices (evidence index, assessor qualifications)
-
-**Tone:** Formal, objective, structured. Reference regulation articles explicitly
-(e.g., "Article 32(1)(a) of Regulation (EU) 2016/679"). Avoid colloquial language.
-
-### Management Report
-
-Concise, business-oriented. Leads with a one-page executive summary. Uses visual
-indicators (counts, heatmap descriptions) rather than technical evidence.
-
-**Key sections:**
-1. Executive summary (1 page max — overall posture, key risks, headline numbers)
-2. Risk heatmap (critical/major/minor counts by category)
-3. Business impact analysis (what gaps mean operationally and financially)
-4. Recommended actions with effort estimates (cost, time, owner)
-5. Progress since last assessment (if prior data available)
-6. Appendix (methodology note, detailed data reference)
-
-**Tone:** Business language, action-oriented. Quantify impact where possible.
-Avoid jargon — explain technical concepts in business terms.
-
----
-
-## Output Conventions
-
-- **File naming:** `{style}-{framework}-{YYYY-MM-DD}.md`
-  - Example: `audit-report-SOC2-2026-03-30.md`
-  - VARS example: `vars-review-report-{acquirer}-2026-03-30.md`
-- **Severity color coding** (for Markdown rendering):
-  - 🔴 Critical | 🟠 Major | 🟡 Minor | 🔵 Observation
-- **Finding IDs:** Preserve original IDs from the input. If absent, assign sequential IDs: `F-001`, `F-002`, etc.
-- **Cross-references:** Link findings to remediation items and evidence appendices by ID.
-
-## Edge Cases
-
-- **No critical findings:** Lead the executive summary with overall compliance posture, not absence of criticals.
-- **Mixed frameworks:** If findings span multiple frameworks (e.g., SOC 2 + PCI DSS), organize by framework first, then by requirement.
-- **Incomplete evidence:** Flag as "Evidence Pending" — do not omit the finding.
-- **Prior assessment data unavailable:** Omit the "Progress" section in Management Report; note "Baseline assessment — no prior data" in methodology.
-- **VARS sub-domain with no findings:** Still include the row in Section 4 and the bullet in Section 3.d — Compliance Status "Satisfactory", Findings and Comments an inline observed-then-finding narrative closing with "No remediation required." (matching the tracker's Satisfactory Issue Description) — Visa expects all nine sub-domains to appear (plus the Third Party Agent row when ATPA is in scope).
-- **VARS legacy numbering:** The official 2025 template skips index 9 in the Section 4 table (Regulatory Risk is labelled #10). The `references/vars-report-template.md` uses sequential 1–9; switch to legacy numbering only if the Visa engagement lead asks.

package/skills/risk-compliance/report-writing/release-check.mjs

@@ -1,93 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-const WEEK_MS = 7 * DAY_MS;
-const here = dirname(fileURLToPath(import.meta.url));
-
-function readJson(path, fallback = {}) {
-  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
-}
-
-function frontmatterValue(text, key) {
-  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
-  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
-  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
-}
-
-function repositoryOf(source) {
-  const value = String(source ?? '').trim();
-  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
-  return match?.[1] ?? null;
-}
-
-function stableVersion(value) {
-  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
-  return match ? match.slice(1).map(Number) : null;
-}
-
-function newer(left, right) {
-  for (let index = 0; index < 3; index += 1) {
-    if (left[index] !== right[index]) return left[index] > right[index];
-  }
-  return false;
-}
-
-function writeCache(path, value) {
-  try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(value));
-  } catch { /* A read-only cache must not block skill use. */ }
-}
-
-function main(now = Date.now()) {
-  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
-  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
-  const name = frontmatterValue(skill, 'name');
-  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
-  if (!name || !localVersion) return;
-
-  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
-  const entry = lock.skills?.[name];
-  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
-  if (!repository) return;
-
-  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
-  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
-  const all = readJson(cachePath);
-  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
-
-  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
-    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 1500,
-    });
-    cache.lastCheck = now;
-    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
-    else delete cache.latestTag;
-    all[repository] = cache;
-    writeCache(cachePath, all);
-  }
-
-  const latestVersion = stableVersion(cache.latestTag);
-  if (!latestVersion || !newer(latestVersion, localVersion)) return;
-  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
-
-  cache.notifiedTag = cache.latestTag;
-  cache.notifiedAt = now;
-  all[repository] = cache;
-  writeCache(cachePath, all);
-  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
-  process.stdout.write(
-    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
-      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
-      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
-  );
-}
-
-try { main(); } catch { /* Update checks are advisory and always fail silent. */ }