@1aboveio/skills 1.0.13 → 1.0.15

package/skills/engineering/test-quality/scripts/persist-conventions-core.mjs

@@ -13,6 +13,12 @@
 // A section sits between `conventions:<id>` markers, so a re-run replaces only
 // that block and keeps everything else, including other skills' sections.
 // Nothing is written without --write: the user triggers the write, not an agent.
+//
+// The guide pointer and a skill's task-entry loader are independent. A link to
+// CONTRIBUTING.md says where the policy lives; it does not load the skill that applies
+// it. So a repo whose AGENTS.md (or regular CLAUDE.md) already names the guide still
+// gets the loader, and a repo that already loads the skill keeps its own rule.
+// engineering's init.mjs reuses `withTaskEntries` for its own two loaders.
 
 import fs from 'node:fs'
 import path from 'node:path'
@@ -20,6 +26,8 @@ import path from 'node:path'
 export const CONTRIBUTING_FILE = 'CONTRIBUTING.md'
 const MENTIONS_CONTRIBUTING = /(?:^|[^\w-])CONTRIBUTING\.md/
 
+const TASK_ENTRY = 'task-entry'
+
 export const AGENTS_SECTION = [
   '## Contributing',
   '',
@@ -69,26 +77,218 @@ export function renderClaude(current) {
   return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
 }
 
-export function persist(repoRoot, section, { write = false } = {}) {
-  const block = sectionBlock(section)
-  const plan = [
-    [CONTRIBUTING_FILE, (text) => renderConventions(text, section.id, block)],
-    ['AGENTS.md', renderAgents],
-    ['CLAUDE.md', renderClaude],
+export function taskEntryMarkers(id) {
+  return [`<!-- conventions:${id}-${TASK_ENTRY}:start -->`, `<!-- conventions:${id}-${TASK_ENTRY}:end -->`]
+}
+
+// Pure: the managed loader block. A short rule in an entrypoint; the conventions it
+// points at stay in CONTRIBUTING.md.
+export function taskEntryBlock({ id, title, body }) {
+  const [start, end] = taskEntryMarkers(id)
+  const recovery = body.includes('After context loss') ? '' : '\nAfter context loss, reload this skill\'s rules before continuing.'
+  return `${start}\n## ${title}\n\n${body.trim()}${recovery}\n${end}\n`
+}
+
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+function withoutExamples(text) {
+  let fence = null
+  let comment = false
+  const active = text.split('\n').map(line => {
+    if (fence) {
+      const match = /^ {0,3}(`{3,}|~{3,})/.exec(line)
+      if (match && match[1][0] === fence[0] && match[1].length >= fence.length
+        && line.slice(match[0].length).trim() === '') fence = null
+      return ''
+    }
+    let masked = ''
+    let cursor = 0
+    while (cursor < line.length) {
+      const marker = line.indexOf(comment ? '-->' : '<!--', cursor)
+      const end = marker < 0 ? line.length : marker
+      masked += comment ? ' '.repeat(end - cursor) : line.slice(cursor, end)
+      if (marker < 0) break
+      const length = comment ? 3 : 4
+      masked += ' '.repeat(length)
+      cursor = marker + length
+      comment = !comment
+    }
+    const match = /^ {0,3}(`{3,}|~{3,})/.exec(masked)
+    if (match) { fence = match[1]; return '' }
+    return /^(?: {4}|\t|\s*>)/.test(line) ? '' : line
+  }).join('\n')
+  if (fence) throw new Error('unclosed Markdown code fence; repair guidance before setup')
+  if (comment) {
+    throw new Error('unclosed HTML comment; repair guidance before setup')
+  }
+  return active
+}
+
+// Keep code-form skill names, but not inline examples containing whole instructions.
+const visible = (text) => withoutExamples(text).replace(/<!--[\s\S]*?-->/g, '')
+  .replace(/(`+)([^`]*?)\1/g, (span, _ticks, content) => /\s/.test(content) ? '' : span)
+
+function hasHeading(text, title) {
+  return new RegExp(`^#{1,6}\\s+${escape(title)}\\s*$`, 'm').test(visible(text))
+}
+
+// A hand-written equivalent ("read and apply the `test-quality` skill") already loads
+// the skill, so the managed block would repeat it. A guide link never matches.
+function loadsSkill(text, skill, contexts = []) {
+  const name = escape(skill)
+  const instruction = new RegExp(`\\b(?:read|load|apply|use|follow)\\s+(?:and\\s+(?:apply|read)\\s+)?(?:(?:the|installed)\\s+){0,2}(?:\`${name}\`|${name}\\s+skills?\\b)`, 'i')
+  return visible(text).split(/\n\s*\n/).some(paragraph =>
+    instruction.test(paragraph)
+    && (!contexts.length || contexts.every(word => new RegExp(`\\b${escape(word)}\\b`, 'i').test(paragraph))))
+}
+
+// Pure: `{ text, conflicts }` — each loader's block added once, where it is missing.
+// An equivalent existing rule is preserved; malformed markers and an unmanaged section
+// under the same heading are reported instead of written over.
+export function withTaskEntries(current, loaders = []) {
+  let text = current
+  const conflicts = []
+  for (const loader of loaders) {
+    const body = visible(text)
+    const denied = new RegExp(`\\b(?:do not|don't|never|must not)\\s+(?:(?:automatically|ever)\\s+)?(?:read|load|apply|use|follow)\\b[^.\\n]{0,120}\\b${escape(loader.skill)}\\b`, 'i')
+    if (denied.test(body)) {
+      conflicts.push(`an existing rule forbids loading "${loader.skill}"; reconcile it before setup`)
+      continue
+    }
+    const restricted = new RegExp(`\\b${escape(loader.skill)}\\b[^.\\n]{0,100}\\bonly\\s+(?:when|if)\\s+(?:explicitly|the user)`, 'i')
+    if (restricted.test(body)) {
+      conflicts.push(`an existing explicit-only rule restricts "${loader.skill}"; reconcile it before setup`)
+      continue
+    }
+    if (loader.contexts?.length && visible(text).split(/\n\s*\n/).some(paragraph =>
+      loadsSkill(paragraph, loader.skill) && /\b(?:for|during)\b[^.\n]{0,80}\bonly\s*[,;:]/i.test(paragraph))) {
+      conflicts.push(`an existing task-only rule restricts "${loader.skill}"; reconcile it before setup`)
+      continue
+    }
+    const [start, end] = taskEntryMarkers(loader.id)
+    const active = withoutExamples(text)
+    const starts = active.split(start).length - 1
+    const ends = active.split(end).length - 1
+    if (starts || ends) {
+      // Already written: a re-run leaves the block as it is rather than refreshing it.
+      if (starts !== 1 || ends !== 1 || active.indexOf(start) > active.indexOf(end)) {
+        conflicts.push(`malformed "${loader.title}" markers; repair them by hand`)
+      } else if (!loadsSkill(active.slice(active.indexOf(start), active.indexOf(end)), loader.skill, loader.contexts)) {
+        conflicts.push(`the preserved "${loader.title}" block has no applicable skill loader; reconcile it before setup`)
+      }
+      continue
+    }
+    if (loadsSkill(text, loader.skill, loader.contexts)) continue
+    if (hasHeading(text, loader.title)) {
+      conflicts.push(`an existing "${loader.title}" section needs manual reconciliation; no competing block added`)
+      continue
+    }
+    text = `${text.replace(/\s*$/, '')}\n\n${taskEntryBlock(loader)}`
+  }
+  return { text, conflicts }
+}
+
+function indexEntries(section) {
+  const loaders = section.loader ? [section.loader] : []
+  return [
+    { name: 'AGENTS.md', render: renderAgents, loaders },
+    // A regular CLAUDE.md that already points at AGENTS.md inherits that file's loaders.
+    { name: 'CLAUDE.md', render: renderClaude, loaders, reachesAgents: true },
   ]
-  return plan.map(([name, render]) => {
-    const file = path.join(repoRoot, name)
-    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) return { file: name, action: 'unchanged' }
-    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
-    const next = render(current)
-    const action = current == null ? 'create' : next === current ? 'unchanged' : 'update'
+}
+
+function reachesSelectedAgents(text, repoRoot, file) {
+  const body = visible(text)
+  const expected = path.join(repoRoot, 'AGENTS.md')
+  const canonical = name => fs.existsSync(name) ? fs.realpathSync(name) : path.resolve(name)
+  const affirmative = body.split('\n').filter(line => !/\b(?:do not|don't|never|must not)\b/i.test(line)).join('\n')
+  const references = [...affirmative.matchAll(/\[[^\]]*\]\((?:<([^>]+)>|([^\s)]+))\)/g)]
+    .map(match => match[1] ?? match[2])
+  for (const match of affirmative.matchAll(/\b(?:read|load|follow|see|consult)\s+`?((?:[^\s`]+\/)?AGENTS\.md)`?/gi)) {
+    references.push(match[1])
+  }
+  return references.some(ref => {
+    if (/^[a-z][a-z\d+.-]*:|^\/\//i.test(ref)) return false
+    try {
+      const target = path.resolve(path.dirname(file), decodeURIComponent(ref.split(/[?#]/)[0]))
+      return canonical(target) === canonical(expected)
+    } catch { return false }
+  })
+}
+
+function apply(repoRoot, entries, write) {
+  repoRoot = fs.realpathSync(repoRoot)
+  const readText = file => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(file))
+  const plannedContent = new Map()
+  const plan = entries.map((entry) => {
+    const file = path.join(repoRoot, entry.name)
+    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) {
+      let conflicts = []
+      try {
+        const target = fs.realpathSync(file)
+        const relative = path.relative(repoRoot, target)
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+          conflicts = ['linked entrypoint is outside the selected project; verify its task loader separately']
+        } else {
+          const current = plannedContent.get(target) ?? readText(file)
+          const checked = withTaskEntries(current, entry.loaders)
+          conflicts = checked.conflicts
+          if (checked.text !== current && !(entry.reachesAgents && reachesSelectedAgents(current, repoRoot, target))) {
+            conflicts.push('linked entrypoint lacks the task loader; explicit reconciliation is required')
+          }
+        }
+      } catch { conflicts = ['linked entrypoint could not be verified; setup is partial'] }
+      return { file: entry.name, action: 'unchanged', conflicts }
+    }
+    const current = fs.existsSync(file) ? readText(file) : null
+    const base = entry.render(current)
+    let next = base
+    let conflicts = []
+    if (base !== LINK_TO_AGENTS) {
+      const applied = withTaskEntries(base, entry.loaders)
+      const inherits = entry.reachesAgents && reachesSelectedAgents(current ?? '', repoRoot, file)
+      next = inherits ? base : applied.text
+      conflicts = applied.conflicts
+    }
     if (next === LINK_TO_AGENTS) {
-      if (write) fs.symlinkSync('AGENTS.md', file)
-      return { file: name, action: 'link' }
+      return { file: entry.name, action: 'link', conflicts, next }
+    }
+    const action = current == null ? 'create' : next === current ? 'unchanged' : 'update'
+    if (current !== null && action !== 'unchanged' && fs.statSync(file).nlink > 1) {
+      conflicts.push('hard-linked guidance cannot be changed without exclusive ownership')
     }
-    if (write && action !== 'unchanged') fs.writeFileSync(file, next)
-    return { file: name, action }
+    plannedContent.set(file, next)
+    return { file: entry.name, action, conflicts, next }
   })
+  const blocked = plan.some(entry => entry.conflicts.length)
+  if (write && !blocked) {
+    for (const entry of plan.filter(entry => entry.action !== 'unchanged')) {
+      const file = path.join(repoRoot, entry.file)
+      fs.accessSync(entry.action === 'create' || entry.action === 'link' ? repoRoot : file, fs.constants.W_OK)
+    }
+    for (const entry of plan) {
+      const file = path.join(repoRoot, entry.file)
+      if (entry.next === LINK_TO_AGENTS) fs.symlinkSync('AGENTS.md', file)
+      else if (entry.action !== 'unchanged') fs.writeFileSync(file, entry.next)
+    }
+  }
+  return plan.map(({ next: _next, ...entry }) => ({
+    ...entry, action: blocked && entry.action !== 'unchanged' ? 'blocked' : entry.action,
+  }))
+}
+
+export function persist(repoRoot, section, { write = false } = {}) {
+  const block = sectionBlock(section)
+  const entries = [
+    { name: CONTRIBUTING_FILE, render: (text) => renderConventions(text, section.id, block), loaders: [] },
+    ...indexEntries(section),
+  ]
+  return apply(repoRoot, entries, write)
+}
+
+// The index half alone: for a section that is already present, only the guide pointer
+// and the task-entry loader are due.
+export function persistIndex(repoRoot, section, { write = false } = {}) {
+  return apply(repoRoot, indexEntries(section), write)
 }
 
 // `section` = { id, owner, title, body }. Exit 0 on success, 2 on a usage error.
@@ -107,12 +307,22 @@ export function runCli(argv, section, { cwd = process.cwd(), log = console.log }
     log(`persist-conventions: not a directory: ${repoRoot}`)
     return 2
   }
-  const results = persist(repoRoot, section, { write })
-  const done = { create: 'created', link: 'linked to AGENTS.md', update: 'updated', unchanged: 'unchanged' }
-  for (const r of results) log(`  ${r.file}: ${write || r.action === 'unchanged' ? done[r.action] : `would ${r.action}`}`)
-  const changed = results.filter((r) => r.action !== 'unchanged').length
+  let results
+  try { results = persist(repoRoot, section, { write }) }
+  catch (error) { log(`persist-conventions: setup refused: ${error.message}`); return 2 }
+  const done = { create: 'created', link: 'linked to AGENTS.md', update: 'updated', unchanged: 'unchanged', blocked: 'blocked' }
+  const conflicts = []
+  for (const r of results) {
+    for (const conflict of r.conflicts ?? []) conflicts.push(`${r.file}: ${conflict}`)
+    log(`  ${r.file}: ${write || r.action === 'unchanged' ? done[r.action] : `would ${r.action}`}`)
+  }
+  const changed = results.filter((r) => !['unchanged', 'blocked'].includes(r.action)).length
   log(write
     ? `persist-conventions: ${section.title}: ${changed} file(s) written, ${results.length - changed} unchanged`
     : `persist-conventions: ${section.title}: preview only, ${changed} file(s) would change; re-run with --write to write`)
-  return 0
+  if (conflicts.length) {
+    for (const conflict of conflicts) log(`  conflict: ${conflict}`)
+    log(`persist-conventions: ${section.title}: ${conflicts.length} conflict(s); no files written; reconcile before setup`)
+  }
+  return conflicts.length ? 2 : 0
 }

package/skills/engineering/test-quality/scripts/persist-conventions.mjs

@@ -1,6 +1,7 @@
 // persist-conventions — the test principles as the `## Testing conventions`
 // section of a repo's CONTRIBUTING.md (../SKILL.md, Persist mode). Run only when
-// the user asks; previews unless --write.
+// the user asks; previews unless --write. --write also adds the skill's task-entry
+// loader to AGENTS.md (and to a regular CLAUDE.md that does not reach AGENTS.md).
 //
 //   node persist-conventions.mjs [--repo-root <dir>] [--write]
 import fs from 'node:fs'
@@ -12,6 +13,17 @@ const SECTION = {
   owner: 'test-quality',
   title: 'Testing conventions',
   body: fs.readFileSync(fileURLToPath(new URL('../references/testing-conventions.md', import.meta.url)), 'utf8'),
+  loader: {
+    id: 'testing',
+    skill: 'test-quality',
+    title: 'Testing task entry',
+    body: [
+      'When writing, changing, or reviewing tests, read and apply the installed',
+      '`test-quality` skill before choosing test shape or adding a gate. The',
+      "repository's testing rules stay in its contributor guide; loading the skill",
+      'adds no new requirement.',
+    ].join('\n'),
+  },
 }
 
 process.exitCode = runCli(process.argv.slice(2), SECTION)

package/skills/risk-compliance/compliance-audit/SKILL.md

@@ -2,7 +2,7 @@
 name: compliance-audit
 version: 2.9.0
 description: "Audit operations against financial-compliance checklists (AML/KYC, VARS, PCI-DSS, TPA oversight, onboarding, transaction monitoring). Produces tracker.md (with a tracker.xlsx export) and phase-trail.md with layered validation; cites evidence by original filename. Input: reg-parser or the built-in VARS checklist."
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Compliance Audit

package/skills/risk-compliance/contract-compare/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: contract-compare
 description: "Compare two or more contracts side-by-side for structured diff, gap analysis, and benchmarking. Use when: comparing contracts or agreements, contract diff, compare terms, vendor-vs-vendor, compare our template vs theirs, compliance gap between contracts. NOT for single-contract risk review — use contract-review for that."
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Contract Compare

package/skills/risk-compliance/contract-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: contract-review
 description: "Review contracts for legal, commercial, and compliance risks via convert → chunk review → merge → validate (+ optional mandate preprocessing). Use for reviewing, auditing, or checking any contract, agreement, NDA, MSA, or SLA; input a file path (PDF/DOCX/TXT) or pasted text."
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Contract Review

package/skills/risk-compliance/doc-authenticity/SKILL.md

@@ -3,7 +3,7 @@ name: doc-authenticity
 version: 0.4.1
 description: "Screen PDF documents and raster images for fabrication, tampering, Photoshop or other image-editor use, and content validity. Detects file type, runs format-specific authenticity forensics, classifies bank statements, conversation logs, invoices, agreements, and other documents, then applies type-specific validity checks. Produces separate authenticity (NO_EVIDENCE_OF_MODIFICATION / SUSPICIOUS / LIKELY_MODIFIED / INCONCLUSIVE) and validity (VALID / INVALID / INCONCLUSIVE) verdicts. Use whenever a user asks whether a document, screenshot, scan, statement, invoice, contract, chat log, receipt, or payment evidence is genuine, original, edited, Photoshopped, manipulated, fake, or valid."
 disable-model-invocation: true
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Document and Image Authenticity

package/skills/risk-compliance/fraud-detection/SKILL.md

@@ -12,7 +12,7 @@ description: >
   impact, and a business report. Use for fraud, scam, mule, account-takeover,
   chargeback, dispute, transfer, collection, or payout risk analysis even when the
   user does not name this skill.
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Fraud Detection

package/skills/risk-compliance/payment-analysis/SKILL.md

@@ -14,7 +14,7 @@ description: >
   transactions" — even if they do not say payment-analysis. Do NOT use for
   fraud rule discovery (fraud-detection) or TLD / MCC-miscoding
   clusters (tld-detection).
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Payment Analysis

package/skills/risk-compliance/portfolio-payment-analysis/SKILL.md

@@ -5,7 +5,7 @@ description: >
   and investigate selected merchants' authorization, settlement and disputes,
   including descriptor mapping and overlapping exports. Portfolio-level payment
   overviews belong to payment-analysis; fraud rule discovery belongs to fraud-detection.
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Portfolio payment analysis

package/skills/risk-compliance/similar-domain/SKILL.md

@@ -8,7 +8,7 @@ description: >
   links, an entity chain, and a watchlist for the operator's next domains.
   Not transaction data (tld-detection) or fraud rules (fraud-detection).
 disable-model-invocation: true
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Similar Domain

package/skills/risk-compliance/tld-detection/SKILL.md

@@ -6,7 +6,7 @@ description: >
   patterns, with USD and BIN-country currency views, group profiles and priorities.
   Not payment-analysis, fraud-detection, or website research.
 disable-model-invocation: true
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # TLD detection