@1aboveio/skills 1.0.14 → 1.0.15

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -369,7 +369,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "d50381c5d34f05b3c4ac60bd0d1a5a56fdeb7112caf3a58303e2c8d5b9cd73d4",
+      "contentDigest": "a91694b84a0cfd014714c53a7b91e3a470fd76daccf85582c21620a4d91523fb",
       "digestExcludes": []
     },
     {
@@ -382,7 +382,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "7fb81756e33e2582cc02b2a964af1361a474ddae64f1304dfdff680162e5f35e",
+      "contentDigest": "8c4c6f21ea637ce24245cf6f20d0aa46d811c35cb8f4b81a78d07907a8c3e8af",
       "digestExcludes": []
     },
     {
@@ -395,7 +395,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "08e07649d8ee91496a4275c9417cd679932d798c91cdbb483ca45979733dd0c3",
+      "contentDigest": "f66eee222aef4ca965a2e9fbfbfc16a95a69213fa30472485519799e9dc99487",
       "digestExcludes": []
     },
     {
@@ -408,7 +408,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "45e72502bf9d1f707caf2990ba8a9bda7fbda4e748b5f798731a1d0d992b0b02",
+      "contentDigest": "647fb4c57154f3e84d4adff0dd44f32a09c8fd6eb0145afbe1141d674e7965db",
       "digestExcludes": []
     },
     {
@@ -421,7 +421,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "5cf9c65216eda37ed0acebcaa97be9eea9239fad96397cdd858b4694cae9d906",
+      "contentDigest": "a9085e135bfbe535f96c4915f8402303e98e663f182b3508376799bff1013763",
       "digestExcludes": []
     },
     {
@@ -434,7 +434,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "6e1c15f7d61a3bb2af78df82b57674152d9c321cc17b5a83d32379cc0a9104ef",
+      "contentDigest": "e21ef0dbc6f4d423b310f78ca342a20aeb672a5fb517a27f3d318e14dacd3f45",
       "digestExcludes": []
     },
     {
@@ -447,7 +447,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "303941d679cacbafc5594a6b8369e016cef3cdf3c065ae919edc8695cbce8a69",
+      "contentDigest": "435361dd2f0aecda06c751825f75d918520203c53ba245b63630eeaa390ae0c5",
       "digestExcludes": []
     },
     {
@@ -460,7 +460,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "d8de3acaf463033d55e5bedf17b5aeac8e9a1d77267c5960af18bdebbaf18c7d",
+      "contentDigest": "fb0eadc4b382a5e6b863d76638949052d24f8c378a74971a0a28ccf43de49e0f",
       "digestExcludes": []
     },
     {
@@ -473,7 +473,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "8b8a149b90292ae4b0c3dd8b34a387ea7fa8c154610c232c8c55ce9781cca03d",
+      "contentDigest": "86660760773ae4869968f5e85efdab6d23e179a02f8c7066bf497f9cc64275c5",
       "digestExcludes": []
     },
     {
@@ -486,7 +486,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "553b2748b6357b92caa30ee29351add044d10cc6ad28e4cdb809f4f23bb5a9da",
+      "contentDigest": "35fc60a6348784ca9b269516a0afddcc8f8e6a2dbb2f281afa657b3abe459450",
       "digestExcludes": []
     },
     {
@@ -499,7 +499,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "65bb8314e2fe1f2ebbdca60f2dcd433af44a8eeba080adf30f0682ef5c0a2acd",
+      "contentDigest": "826e64ed07b75f1ba24da7cac6c6e67b4f8152f5c34e067548f1af24038a3fa0",
       "digestExcludes": []
     },
     {
@@ -512,13 +512,13 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "9fb61a9e59fee73ff803113e9d33e47bc19a2ef5ce92c06f63a4d5cca8a72189",
+      "contentDigest": "0fc35665e627e1c1698ba10a1c9d00a3745df10c22562b7a3ef72267e2309c4b",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "d0f4c3cc3c13714b4d4be17f6b8b1f56aff7fe1901be7c7823f4faba348baeb6",
+  "releaseIdentity": "30ddab5b3c21191385d102158a2eb2bd3dcbd6e82d350777722543931e01ad44",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",

package/skills/engineering/ensure-coverage/SKILL.md

@@ -2,7 +2,7 @@
 name: ensure-coverage
 description: "Define or audit behavior-first test criteria — ACs, required test levels, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT judging whether a single test is any good (test-quality), authoring browser tests (e2e-test), reviewing a PR (better-review), or delivering issues (resolve-issues)."
 disable-model-invocation: true
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Ensure Coverage

package/skills/engineering/golden-path/SKILL.md

@@ -3,7 +3,7 @@ name: golden-path
 description: "Golden-path E2E: the short list of user journeys whose failure blocks a release, kept in a repo as one contract (golden-paths.json) with a generated GOLDEN_PATHS.md and a generated GitHub Actions workflow, and run against a local build or a deployed URL for an ALIVE/DEAD verdict. Use to set golden paths up in a repo ('init golden paths', 'add golden-path CI'), to migrate an older smoke.manifest.json or a hand-built smoke setup ('audit', 'migrate smoke'), to add, change, or remove a golden path, to ask 'is the build alive?' or run them before a PR or release, or when a change touches a flow listed in GOLDEN_PATHS.md. NOT for writing the Playwright specs themselves (e2e-test), deciding what a change must prove (ensure-coverage), or general workflow YAML (github-actions)."
 dependencies:
   - e2e-test
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Golden path

package/skills/engineering/harness-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: harness-runtime
 description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Harness Runtime

package/skills/engineering/resolve-issues/SKILL.md

@@ -8,7 +8,7 @@ dependencies:
   - better-review
   - golden-path
   - harness-runtime
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve issues

package/skills/engineering/resolve-issues/references/review.md

@@ -9,7 +9,10 @@ restate its rules in the brief beyond the two below.
 ## Brief
 
 - Reviewer model: a different id from the implementer's
-  ([preflight.md](preflight.md#1-model-slots)).
+  ([preflight.md](preflight.md#1-model-slots)). Take its model id and effort from
+  the plan's recorded reviewer slot, a model or effort the human named included,
+  and pass them as structured launch arguments (the spawn's model and effort
+  fields), never as brief text and never a model id hardcoded here.
 - Context: spec, repository standards, target branch, unit branch and HEAD,
   parent PR when stacked or chained, exploration path, and the contracts the unit
   provides and builds on.
@@ -92,6 +95,25 @@ pass (incomplete, an open P0/P1, a GitHub re-review awaited): pick the tier
 instead. Example: round 2 passed on
 `5f63348`; CI failed and the fix pushed `2035c74`: carry, no reviewer.
 
+### Resume an incomplete review
+
+An incomplete review is unfinished work, not evidence of a bad patch: start no
+fix round. Before another launch, read the retained record for unfinished passes,
+completed commands and findings, and why the review stopped. Resolve an open
+`executionIncident` first; ask the reviewer to record missing continuation details.
+
+For the same valid HEAD and scope, resume the same reviewer in the same round
+using its result file, review clone and retained context. Give it the unfinished
+work rather than repeating the whole assignment; preserve completed valid passes.
+A wrong HEAD or invalid scope must be corrected, not carried as completed proof.
+
+If that reviewer cannot continue, state why replacement is necessary, which
+retained evidence the replacement reads, and what it redoes before launching it.
+The replacement reviews every pass with `tier: "full"`. Keep the round number,
+`fixRound`, unit `attempt` and earlier round files; incompleteness neither resets
+history nor counts as progress. Use the plan's recorded model and effort in
+structured launch arguments as [the brief](#brief) requires.
+
 ## GitHub reviews
 
 Count reviews posted on the PR by any account with write access other than
@@ -135,8 +157,9 @@ the PR author; `github-reviews.mjs` reads them and decides what blocks.
    completed review left a P0/P1 open, so skips, and any review that follows
    a passing one, never consume a fix cycle; another attempt after a
    completed blocker does, even with an unchanged patch, so fix first.
-   Resume an incomplete review in the same round with the same reviewer when
-   it can continue; a new reviewer that replaces it reviews in full and keeps
+   Resume an incomplete review in the same round
+   ([Resume an incomplete review](#resume-an-incomplete-review)); a new
+   reviewer that replaces it reviews in full and keeps
    the prior counter. Legacy records without
    `fixRound` use their attempt number; never reset history. The verdict checks the counter against the immediate prior, given
    with `--prior` when the review's filename is not `<unit>-r<N>.json`. The
@@ -178,7 +201,7 @@ the PR author; `github-reviews.mjs` reads them and decides what blocks.
    | `handback` | `not-converging`: stop fixing; mark the unit `blocked` (`blockedReason: review-handback`) and defer the PR and its open findings on its issue |
    | `decide` | `spec-question`: the printed `decide` file holds the question. Answer it ([expire.md](expire.md#decide-before-you-defer)) as a `decisions` entry whose `answers` names that file, then rerun this step with `--decision <its id>`: it writes a `test-first` fix brief that carries the decision |
    | `wait` | No P0/P1 is open, but `awaiting` names a reviewer whose changes request a fix already answered: request their re-review (`gh pr edit <N> --add-reviewer <login>`) and keep the other units shipping; rerun step 3 on each completion notice, or every 5 minutes when nothing else runs; after 30 minutes, mark the unit `blocked` (`blockedReason: review-handback`) and defer it on its issue |
-   | `review-again` | Review incomplete (`complete` not true, passes, unresolved incident, no checks, P2 with neither a URL nor a dropbox id, wrong HEAD, or a skip the rerun no longer confirms): resolve any incident, then resume or spawn the reviewer for the same round; start no fix round |
+   | `review-again` | Review incomplete (`complete` not true, passes, unresolved incident, no checks, P2 with neither a URL nor a dropbox id, wrong HEAD, or a skip the rerun no longer confirms): resolve any incident, then [resume the same reviewer, or replace it and say what changes](#resume-an-incomplete-review), for the same round; start no fix round |
    | (exit 2, no verdict) | The script could not run: fix the command or path |
 
 ## What blocks

package/skills/engineering/resolve-release/SKILL.md

@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release f
 disable-model-invocation: true
 metadata:
   workflow-role: coordinator
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve release

package/skills/engineering/rush-issues/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-issues
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush issues (shortcut of resolve-issues)

package/skills/engineering/rush-release/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-release
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush release (shortcut of resolve-release)

package/skills/engineering/test-quality/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: test-quality
 description: "Seven principles for tests that catch real bugs, and an audit that reports weak, redundant, and not-coverage tests without fixing them. Use when writing, changing, or reviewing tests, or when asked whether tests are useful, redundant, over-mocked, flaky, only assert static text, or test config files, or asked to make a slow test suite faster without losing coverage, or when the user asks to write the testing conventions into a repo's CONTRIBUTING.md. NOT defining what a spec must prove (ensure-coverage) or authoring browser tests (e2e-test)."
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Test Quality
@@ -82,6 +82,8 @@ node "$SKILL_DIR/scripts/persist-conventions.mjs" --write   # write, once the us
 
 It writes the seven principles ([references/testing-conventions.md](references/testing-conventions.md)) as the `## Testing conventions` section of `CONTRIBUTING.md`, between `conventions:testing` markers: a re-run replaces only that section and keeps everything else, including the `## CI conventions` and `## Delivery` sections `github-flow` writes. It adds a pointer to `AGENTS.md` unless that already names `CONTRIBUTING.md`, and creates a missing `CLAUDE.md` as a symlink to `AGENTS.md` (a regular `CLAUDE.md` that names neither file gets the pointer); missing files are created. `CONTRIBUTING.md` is the file `code-review` reads as a standards source, so the principles then apply in review too. Report each file's result line; committing is the user's call.
 
+The same run also adds one `## Testing task entry` rule to `AGENTS.md`, between `conventions:testing-task-entry` markers: when writing, changing, or reviewing tests, read and apply this skill. It is a separate check from the guide pointer — a repo whose `AGENTS.md`, or whose regular `CLAUDE.md`, already names `CONTRIBUTING.md` still gets it, because a link says where the rules live, not that the skill is loaded. The rule routes to this skill and states no new requirements; the principles stay in `CONTRIBUTING.md`. An entrypoint that already loads `test-quality`, an unmanaged section with that heading, or malformed markers is preserved and reported instead of duplicated, and a `CLAUDE.md` that points at `AGENTS.md` inherits the rule rather than a copy. Repeating the run changes nothing.
+
 ## The lint
 
 Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file from, never your CWD. `node "$SKILL_DIR/scripts/lint-tests.mjs"` scans the tree; `--diff <base>` only lines changed since the merge-base. A tool-local **gate** rule fails the command's exit status; it is not automatically a repository merge requirement. Assess optional hits in context and preserve existing adopted gates. Rules, flags, and what a clean run proves (little, for Python and Go): [references/lint.md](references/lint.md).

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.46.0
+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.46.0
+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.46.0
+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.46.0
+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.46.0
+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.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Payment Analysis