@1aboveio/skills 1.0.14 → 1.0.16

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.46.0
+release-version: 0.48.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.46.0
+release-version: 0.48.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.46.0
+release-version: 0.48.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Engineering
@@ -140,7 +140,7 @@ resolve the destination before any issue creation. Never infer a Linear project.
 
 | File or section | Init owns |
 | --- | --- |
-| `AGENTS.md` | Missing pointer to `CONTRIBUTING.md`; no policy 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),
@@ -152,12 +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 loader. A
+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
@@ -192,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 and tracker routing, written as `CONTRIBUTING.md` sections; `AGENTS.md` gets only the loading pointer | 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 |
@@ -38,7 +38,10 @@ 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.
 Project policy is persisted in `CONTRIBUTING.md`, so `AGENTS.md` keeps only the short
-loader. A `Feature delivery` section written into `AGENTS.md` by an earlier release
+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

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

@@ -44,8 +44,10 @@ comments before recording their hashes. Do not rewrap existing text or claim it
 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 loading pointer. Record a new
-pointer as an `engineering:<id>` loading addition, never as a policy section.
+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

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

@@ -3,9 +3,21 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 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) {
@@ -65,6 +78,7 @@ function sectionState(current, title, id) {
   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 -->`)
@@ -121,7 +135,7 @@ function planInitialization(root, options) {
     throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
   }
 
-  // AGENTS.md loads the policy; it does not carry it. Init adds only the pointer.
+  // 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.
@@ -130,6 +144,9 @@ function planInitialization(root, options) {
   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.`)
   }
+  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')
@@ -144,14 +161,22 @@ function planInitialization(root, options) {
   contributingText = addSection(contributingText, 'Issue tracking', 'tracker',
     trackerBody(options.githubRepo ?? githubRepo(root), options.linearProjects))
 
+  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: [
-      { ...agents, next: agentText },
-      { ...contributing, next: contributingText },
+    entries,
+    notes: [
+      ...(featureDeliveryInAgents
+        ? ['Feature delivery stays in AGENTS.md; no competing section added to CONTRIBUTING.md']
+        : []),
     ],
-    notes: featureDeliveryInAgents
-      ? ['Feature delivery stays in AGENTS.md; no competing section added to CONTRIBUTING.md']
-      : [],
   }
 }
 

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
 }

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

@@ -1,6 +1,8 @@
 // persist-conventions — the tracker routing rules as the `## Issue tracking`
-// section of a repo's CONTRIBUTING.md (../SKILL.md, First use in a repo).
+// section of a repo's CONTRIBUTING.md (../SKILL.md, Tracker routing).
 // Previews unless --write; --if-missing leaves an existing section alone.
+// --write also adds the skill's task-entry loader for issue and spec creation to
+// AGENTS.md (and to a regular CLAUDE.md that does not reach AGENTS.md).
 //
 //   node persist-conventions.mjs [--repo-root <dir>] [--github-repo <owner/name>]
 //     [--linear-project <name>]... [--if-missing] [--write]
@@ -10,11 +12,24 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
-import { CONTRIBUTING_FILE, LINK_TO_AGENTS, markers, renderAgents, renderClaude, runCli } from './persist-conventions-core.mjs'
+import { CONTRIBUTING_FILE, markers, persistIndex, runCli } from './persist-conventions-core.mjs'
 
 const ID = 'tracker'
 const TEMPLATE = fs.readFileSync(fileURLToPath(new URL('../references/tracker-conventions.md', import.meta.url)), 'utf8')
 
+// Scoped to issue and spec creation: this is tracker persistence, not a general
+// invitation to load the engineering defaults into every task.
+const LOADER = {
+  id: 'tracker',
+  skill: 'engineering',
+  title: 'Tracker task entry',
+  body: [
+    'Before creating an issue, spec, epic, or sub-issue, read and apply the installed',
+    "`engineering` skill's tracker routing. This setup installs tracker routing only;",
+    "the project's routing rules stay in its contributor guide. It selects no other workflow.",
+  ].join('\n'),
+}
+
 function githubRepoFromRemote(url) {
   const m = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(url.trim())
   return m ? m[1] : null
@@ -27,22 +42,18 @@ function renderBody(githubRepo, linearProjects) {
   return TEMPLATE.replaceAll('{{githubRepo}}', githubRepo).replaceAll('{{linearProjects}}', linear)
 }
 
-// The section stays as it is; only a missing AGENTS.md index or CLAUDE.md link is added.
-function indexOnly(repoRoot, write, log) {
-  let changed = 0
-  for (const [name, render] of [['AGENTS.md', renderAgents], ['CLAUDE.md', renderClaude]]) {
-    const file = path.join(repoRoot, name)
-    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) continue
-    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
-    const next = render(current)
-    if (next === current) continue
-    changed++
-    log(`  ${name}: ${write ? 'written' : 'would change'}`)
-    if (!write) continue
-    if (next === LINK_TO_AGENTS) fs.symlinkSync('AGENTS.md', file)
-    else fs.writeFileSync(file, next)
+// The section stays as it is; only a missing AGENTS.md pointer or CLAUDE.md link and
+// the missing task-entry loader are added.
+function indexOnly(repoRoot, section, write, log) {
+  const results = persistIndex(repoRoot, section, { write })
+  const conflicts = results.flatMap(result => result.conflicts ?? [])
+  for (const result of results) {
+    for (const conflict of result.conflicts ?? []) log(`  ${result.file}: ${conflict}`)
+    if (result.action === 'blocked') log(`  ${result.file}: blocked`)
+    else if (result.action !== 'unchanged') log(`  ${result.file}: ${write ? 'written' : 'would change'}`)
   }
-  return changed ? `${changed} index file(s) ${write ? 'written' : 'would change'}` : 'nothing written'
+  const changed = results.filter((result) => !['unchanged', 'blocked'].includes(result.action)).length
+  return { summary: changed ? `${changed} index file(s) ${write ? 'written' : 'would change'}` : 'nothing written', blocked: conflicts.length > 0 }
 }
 
 function main(argv, { log = console.log } = {}) {
@@ -73,12 +84,28 @@ function main(argv, { log = console.log } = {}) {
     const file = path.join(repoRoot, CONTRIBUTING_FILE)
     const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
     if (current.includes(markers(ID)[0])) {
-      log(`persist-conventions: Issue tracking: section already present; ${indexOnly(repoRoot, argv.includes('--write'), log)}`)
-      return 0
+      const section = sectionFor(githubRepo, linearProjects)
+      const indexed = indexOnly(repoRoot, section, argv.includes('--write'), log)
+      log(`persist-conventions: Issue tracking: section already present; ${indexed.summary}`)
+      return indexed.blocked ? 2 : 0
     }
   }
-  const section = { id: ID, owner: 'engineering', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
+  const section = sectionFor(githubRepo, linearProjects)
   return runCli(rest, section, { log })
 }
 
-process.exitCode = main(process.argv.slice(2))
+function sectionFor(githubRepo, linearProjects) {
+  return {
+    id: ID,
+    owner: 'engineering',
+    title: 'Issue tracking',
+    body: renderBody(githubRepo, linearProjects),
+    loader: LOADER,
+  }
+}
+
+try { process.exitCode = main(process.argv.slice(2)) }
+catch (error) {
+  console.error(`persist-conventions: setup refused: ${error.message}`)
+  process.exitCode = 2
+}

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

@@ -3,7 +3,7 @@ name: engineering-runtime
 description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.46.0
+release-version: 0.48.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Engineering Runtime