@1aboveio/skills 1.0.13 → 1.0.15

package/skills/engineering/better-review/SKILL.md

@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/better-review). Single-agent adversarial rev
 disable-model-invocation: true
 dependencies:
   - engineering-runtime
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Better Review

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

@@ -1,7 +1,7 @@
 ---
 name: e2e-test
 description: "Playwright end-to-end guidance for affected browser journeys, render health and presentation checks, with route manifests and sweeps for broader audits. Use when browser routes or user flows ship or change, or a Playwright test flakes. NOT for non-browser tests, defining what to test (ensure-coverage), the curated ALIVE/DEAD golden-path gate (golden-path), or CI workflow YAML (github-actions)."
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # E2E Testing Standard

package/skills/engineering/engineering/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: engineering
 description: "Engineering conventions: feature-delivery priorities, focused verification and review, operational boundaries, and tracker routing. Standalone /engineering offers Global, Project, or Session setup and targeted resets for configured scopes; /engineering init keeps explicit project setup. Use when setting up AGENTS.md or CONTRIBUTING.md, saving or resetting engineering defaults, or before creating an engineering issue, spec, epic, ticket, or sub-issue on GitHub or Linear. Reads existing policy without writing during ordinary work. NOT the issue-to-PR workflow (resolve-issues), release execution (resolve-release), Git delivery (github-flow), or CI setup (github-actions)."
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Engineering
@@ -140,8 +140,8 @@ resolve the destination before any issue creation. Never infer a Linear project.
 
 | File or section | Init owns |
 | --- | --- |
-| `AGENTS.md` | Missing `Feature delivery` section and a pointer to `CONTRIBUTING.md` |
-| `CONTRIBUTING.md` | Missing `Engineering conventions`, `Testing conventions`, and `Issue tracking` sections |
+| `AGENTS.md` | Missing pointer to `CONTRIBUTING.md` and the short skill task routing rule; no policy sections |
+| `CONTRIBUTING.md` | Missing `Feature delivery`, `Engineering conventions`, `Testing conventions`, and `Issue tracking` sections |
 
 The templates are [feature delivery](references/feature-delivery.md),
 [engineering conventions](references/engineering-conventions.md),
@@ -152,6 +152,25 @@ without invoking its writer. `test-quality` owns the testing rules and deliberat
 updates; init only adds a missing section. The [skill review](references/init-scope.md)
 explains what is included and what remains opt-in.
 
+Project policy lives in `CONTRIBUTING.md`; `AGENTS.md` carries only the loaders. A
+`Feature delivery` section already in `AGENTS.md`, including one an earlier init wrote,
+stays where it is: init neither migrates nor deletes it, and it does not add a competing
+copy to `CONTRIBUTING.md`. Existing `CONTRIBUTING.md` policy wins the same way.
+Initialization moves no existing rules between files and refreshes neither.
+
+Besides the guide pointer, `AGENTS.md` gains short task routing rules: read this
+skill before engineering implementation, review, planning, or issue creation, and read
+`test-quality` when writing or reviewing tests. It names the skills because a
+`CONTRIBUTING.md` link only loads policy, not the skills that apply it. Init adds it
+only for a missing skill loader; a rule for one skill does not configure the other.
+Equivalent active rules stay unchanged, and an unrecognized routing section requires
+reconciliation rather than a competing rule. Loading does not authorize running init,
+writing files, or calling other workflows; setup stays an explicit request. Verify
+that supported entrypoints reach both loaders and contributor guidance; report partial
+setup if a separate entrypoint misses either. Init still does not edit `CLAUDE.md`.
+Existing task-only or explicit-only rules do not establish broader coverage; preserve
+them and report a conflict where the requested loader would contradict their limit.
+
 Existing sections, including legacy `conventions:tracker` blocks written by
 `contributing`, are preserved byte-for-byte. Repeated init is not a refresh and
 leaves manual edits unchanged. No force/update mode is implied. If policy needs to
@@ -186,7 +205,9 @@ Before creating work:
    product acceptance.
 
 The retained tracker-only helper supports explicit requests to persist or update
-that section:
+that section and its scope-limited `engineering` task-entry loader in agent
+entrypoints. That loader covers issue/spec creation only; it does not configure
+the general engineering-work loader installed by Project/init:
 
 ```sh
 node "$SKILL_DIR/scripts/persist-conventions.mjs" --repo-root <project-root> \

package/skills/engineering/engineering/references/init-scope.md

@@ -15,7 +15,7 @@ not initialization sources; pinned external skills keep their upstream ownership
 
 | Skill | Include in guidance | Keep as a separate action |
 | --- | --- | --- |
-| engineering (formerly contributing) | Feature priorities, guidance lookup, tracker routing | Tracker refresh or project-policy changes |
+| engineering (formerly contributing) | Feature priorities, guidance lookup and tracker routing, written as `CONTRIBUTING.md` sections; `AGENTS.md` gets the guide pointer and a short rule to load `engineering` for engineering work and `test-quality` for tests | Tracker refresh or project-policy changes |
 | resolve-issues | Agreed outcome, bounded supporting work, explicit stopping point | Issue planning, workers, PRs, scheduling |
 | rush-issues | Same delivery principles as resolve-issues | Shortcut workflow invocation |
 | ensure-coverage | Smallest sufficient proof, stable acceptance, required checks preserved | Ledger adoption, broad audits, new gates |
@@ -37,8 +37,15 @@ not call other skills' convention writers: they own their sections and may need
 additional decisions. Init reads `test-quality`'s canonical template directly;
 the testing owner and `conventions:testing` section identity remain unchanged.
 Existing project sections, including old testing and tracker blocks, stay unchanged.
-Delivery, CI, and Data Catalog conventions require separate explicit setup with
-their owning skills. Setup may point to these capabilities without requiring them.
+Project policy is persisted in `CONTRIBUTING.md`, so `AGENTS.md` keeps only the short
+loaders: the guide pointer, plus a rule naming the skills to read for engineering work
+and for tests. An existing equivalent rule is preserved rather than duplicated, and the
+rule loads skills without authorizing setup. A `Feature delivery` section written into
+`AGENTS.md` by an earlier release
+stays there: init does not migrate or delete it, and it does not add a competing copy
+to `CONTRIBUTING.md`. Delivery, CI, and Data Catalog conventions require separate
+explicit setup with their owning skills. Setup may point to these capabilities without
+requiring them.
 
 Stack-specific tools, commands, cloud projects, release branches, required gates,
 and golden paths are project facts, not defaults to manufacture. Read established

package/skills/engineering/engineering/references/scope-management.md

@@ -43,6 +43,12 @@ new global defaults or new loading pointer in unique `engineering:<id>:start/end
 comments before recording their hashes. Do not rewrap existing text or claim it as
 owned. Keep existing valid records and add only new entries; deduplicate entries.
 
+Project policy sections, including `Feature delivery` (`conventions:feature-delivery`),
+live in `CONTRIBUTING.md`; `AGENTS.md` holds only the guide pointer and skill task-entry
+loaders. Task-entry blocks use their stable `conventions:<id>-task-entry` markers;
+record only blocks newly added by this setup, independently for each skill. Record a
+new guide pointer as an `engineering:<id>` loading addition, never as a policy section.
+
 Set `createdFile` only when this save created that file. Preserve unrelated bytes
 and existing links. Do not create a sidecar, global settings entry, or project file
 for a session choice. A repeated save with no additions leaves files unchanged.
@@ -73,6 +79,11 @@ scope's saved defaults, not a reinstall, refresh, or reset of every scope.
 5. Remove owned loading pointers only if they are unchanged and no longer needed
    by retained guidance. Keep a pointer that still loads user policy. Remove an
    empty ownership record and any empty wrapper heading added by this save.
+   For a legacy `Feature delivery` section in `AGENTS.md`, honor a valid existing
+   ownership record and unchanged hash under step 3, even if an earlier initializer
+   recorded it. Preserve and report unrecorded or edited policy under step 4; do not
+   infer ownership from its location or migrate it during reset. Keep the pointer
+   while retained `CONTRIBUTING.md` policy still needs it.
    Delete a file only if `createdFile` proves this skill created it and nothing
    except the original generated title and whitespace remains. Preserve pre-existing
    files, symlinks, hand edits, and unrelated sections; never delete an instruction

package/skills/engineering/engineering/scripts/init.mjs

@@ -2,10 +2,22 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { withTaskEntries } from './persist-conventions-core.mjs'
 
 const reference = name => fs.readFileSync(fileURLToPath(new URL(`../references/${name}.md`, import.meta.url)), 'utf8').trim()
 const usage = 'node init.mjs [--repo-root <dir>] [--github-repo <owner/name>] [--linear-project <name>]... [--write]'
+const taskLoaders = [
+  {
+    id: 'engineering', skill: 'engineering', title: 'Engineering skills',
+    contexts: ['implementation', 'review', 'planning', 'issue creation'],
+    body: 'Before engineering implementation, review, planning, or issue creation, read and apply the installed `engineering` skill. After context loss, reload its rules before continuing. Loading it does not authorize initialization, project writes, or unrelated workflows.',
+  },
+  {
+    id: 'testing', skill: 'test-quality', title: 'Testing task entry',
+    body: 'When writing, changing, or reviewing tests, read and apply the installed `test-quality` skill. After context loss, reload its rules before continuing. Follow the testing conventions in the contributor guide; loading the skill adds no new gates or write permissions.',
+  },
+]
 
 function parseArgs(argv) {
   const options = { write: false, linearProjects: [] }
@@ -45,8 +57,9 @@ function inspectTarget(root, name) {
   if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
     throw new Error(`${name} resolves outside the selected project`)
   }
-  if (!fs.statSync(target).isFile()) throw new Error(`${name} is not a regular file`)
-  return { name, file, target, current: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(target)) }
+  const info = fs.statSync(target)
+  if (!info.isFile()) throw new Error(`${name} is not a regular file`)
+  return { name, file, target, nlink: info.nlink, current: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(target)) }
 }
 
 function append(current, body) {
@@ -54,7 +67,7 @@ function append(current, body) {
   return `${current}${separator}${body.trim()}\n`
 }
 
-function preserveOrAdd(current, title, id, body) {
+function sectionState(current, title, id) {
   const start = `<!-- conventions:${id}:start -->`
   const end = `<!-- conventions:${id}:end -->`
   const starts = current.split(start).length - 1
@@ -62,8 +75,13 @@ function preserveOrAdd(current, title, id, body) {
   if (starts !== ends || starts > 1 || (starts && current.indexOf(start) > current.indexOf(end))) {
     throw new Error(`malformed ${title} section markers; preserve and repair existing guidance first`)
   }
-  if (starts || current.split(/\r?\n/).some(line => line.trim() === `## ${title}`)) return current
-  return append(current, `${start}\n${body}\n${end}`)
+  return Boolean(starts) || current.split(/\r?\n/).some(line => line.trim() === `## ${title}`)
+}
+
+
+function addSection(current, title, id, body) {
+  if (sectionState(current, title, id)) return current
+  return append(current, `<!-- conventions:${id}:start -->\n${body.trim()}\n<!-- conventions:${id}:end -->`)
 }
 
 function linkFrom(from, to) {
@@ -73,11 +91,14 @@ function linkFrom(from, to) {
 function hasLoader(current, from, to) {
   const links = /\[[^\]\r\n]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"'\r\n]*["'])?\s*\)/g
   for (const match of current.matchAll(links)) {
-    const href = (match[1] ?? match[2]).split(/[?#]/)[0]
+    const href = match[1] ?? match[2]
     if (!href || /^[a-z][a-z\d+.-]*:|^\/\//i.test(href)) continue
     let target
     try {
-      target = path.resolve(path.dirname(from.target), decodeURIComponent(href))
+      const link = new URL(href, pathToFileURL(from.target))
+      if (link.hash) continue
+      link.search = ''
+      target = fileURLToPath(link)
     } catch {
       continue
     }
@@ -114,23 +135,49 @@ function planInitialization(root, options) {
     throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
   }
 
-  let agentText = preserveOrAdd(agents.current ?? '# Agent instructions\n', 'Feature delivery',
-    'feature-delivery', reference('feature-delivery'))
+  // AGENTS.md routes tasks and loads policy; it does not carry the policy itself.
+  const agentBase = agents.current ?? '# Agent instructions\n'
+  // An earlier release put Feature delivery in AGENTS.md. That policy stays where it is:
+  // init neither migrates it nor adds a competing copy to CONTRIBUTING.md.
+  const featureDeliveryInAgents = sectionState(agentBase, 'Feature delivery', 'feature-delivery')
+  let agentText = agentBase
   if (!hasLoader(agentText, agents, contributing)) {
     agentText = append(agentText, `## Contributing\n\nFollow [CONTRIBUTING.md](${linkFrom(agents, contributing)}) for this project's engineering conventions and existing delivery requirements.`)
   }
-
-  let contributingText = preserveOrAdd(contributing.current ?? '# Contributing\n', 'Engineering conventions',
+  const routing = withTaskEntries(agentText, taskLoaders)
+  if (routing.conflicts.length) throw new Error(routing.conflicts.join('; '))
+  agentText = routing.text
+
+  let contributingText = contributing.current ?? '# Contributing\n'
+  const featureDeliveryInContributing = sectionState(contributingText, 'Feature delivery', 'feature-delivery')
+  if (!featureDeliveryInAgents && !featureDeliveryInContributing) {
+    contributingText = addSection(contributingText, 'Feature delivery', 'feature-delivery',
+      reference('feature-delivery'))
+  }
+  contributingText = addSection(contributingText, 'Engineering conventions',
     'engineering', reference('engineering-conventions'))
   const testing = fs.readFileSync(new URL('../../test-quality/references/testing-conventions.md', import.meta.url), 'utf8').trim()
-  contributingText = preserveOrAdd(contributingText, 'Testing conventions', 'testing', testing)
-  contributingText = preserveOrAdd(contributingText, 'Issue tracking', 'tracker',
+  contributingText = addSection(contributingText, 'Testing conventions', 'testing', testing)
+  contributingText = addSection(contributingText, 'Issue tracking', 'tracker',
     trackerBody(options.githubRepo ?? githubRepo(root), options.linearProjects))
 
-  return [
+  const entries = [
     { ...agents, next: agentText },
     { ...contributing, next: contributingText },
   ]
+  for (const entry of entries) {
+    if (entry.current !== entry.next && entry.nlink > 1) {
+      throw new Error(`${entry.name} is hard-linked; setup requires exclusive ownership`)
+    }
+  }
+  return {
+    entries,
+    notes: [
+      ...(featureDeliveryInAgents
+        ? ['Feature delivery stays in AGENTS.md; no competing section added to CONTRIBUTING.md']
+        : []),
+    ],
+  }
 }
 
 function main(argv) {
@@ -142,13 +189,14 @@ function main(argv) {
   const selected = options.repoRoot ?? gitOutput(process.cwd(), ['rev-parse', '--show-toplevel']) ?? process.cwd()
   const root = fs.realpathSync(selected)
   if (!fs.statSync(root).isDirectory()) throw new Error('project root is not a directory')
-  const plan = planInitialization(root, options)
+  const { entries, notes } = planInitialization(root, options)
   console.log(`engineering init: ${options.write ? 'write' : 'preview only'} (${root})`)
-  for (const entry of plan) {
+  for (const entry of entries) {
     const action = entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update'
     if (options.write && action !== 'unchanged') fs.writeFileSync(entry.target, entry.next)
     console.log(`  ${entry.name}: ${!options.write && action !== 'unchanged' ? 'would ' : ''}${action}`)
   }
+  for (const note of notes) console.log(`  note: ${note}`)
   console.log('Existing sections are preserved; initialization does not refresh project policy or authorize delivery actions.')
 }
 

package/skills/engineering/engineering/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
 }