@abarcenas/ai-workflow-template 1.46.0 → 1.47.0

package/.agents/instructions/learned-knowledge.instructions.md

@@ -577,3 +577,21 @@
 - **coder (index audits)**: Enumerate all mutating paths — create, update, shrink, delete-source, failure — then assert the same invariant helper on each. The bug was in the paths that had never been tested, not in the one that had.
 - **deployer**: This was a **follow-up fix** to a bug deliberately recorded as open in commit `308c90f`; the tracker entry must explicitly mark that follow-up **resolved** so the audit trail does not keep an open defect that no longer exists. Re-run all three gates before and after, stage only the enumerated files, and use `SKIP_BUMP=1` so the fix does not bump the minor version.
 - **all agents (knowledge retrieval)**: `memory_search` returned "No results found. The index may be empty"; `knowledgebase_search` was **not executed** (PG vector unavailable — `DATABASE_URL` not configured). Both reported as skipped/unavailable, neither retried, neither treated as a task failure.
+
+## Session: 2026-10-25 — Project-Owned Layer for Sync (ownership before force; formatter freeze hazard)
+
+**Pipeline:** implementer → coder → reviewer (round 1: APPROVE WITH CHANGES) → coder → reviewer (round 2: BLOCK) → coder (round 3 fixes) → tracker
+**Scope:** `scripts/sync.js`, `scripts/sync-unit.test.js`, `.prettierignore`, `AGENTS.md`, `README.md`, `package.json`, `opencode.mcp.example.json`
+**Verification:** 26 files / **790 tests**, 0 failures; coverage **96.88 / 94.9 / 96.87 / 97.09**; `npm pack --dry-run` ships `.prettierignore` and excludes `AGENTS.project.md` and `opencode.json`; consumer repos untouched (apmc-cms: only its three pre-existing modified files; apmc-v2 clean).
+
+**New knowledge:**
+- **Sync mechanics, decided once and recorded here:** the overwrite policy is **hash-equality**; a file whose hash does not match is skipped **permanently** and only refreshes if the consumer writes it again. `--force` is destructive with **no backup**. Prune is **opt-in** and is never passed by the setup command. `opencode.json` looked managed (it sat in `rootFiles` at HEAD) but was excluded from the tarball with no manifest key, so it was effectively scaffold-once — **verify tarball + manifest key + copy loop before assuming any file is managed.**
+- **Design pattern that worked:** check ownership **before** the `forceOverwrite || isUntouched` branch, and short-circuit prune on ownership **before** hashing. A guard placed after either decision point does not hold — the file is already copied or already queued for deletion. One exported `Set` matching channel-agnostically (root name also protects nested names) is deliberately over-conservative and easier to keep correct than four parallel checks.
+- **Testing pattern that failed:** writing the shipped file verbatim as the test fixture only proved the parser agreed with itself — it passed while the detector was wrong in both directions. What caught it was a **table-driven matrix with both outcomes asserted** (false alarm *and* false all-clear) plus **parent-directory-protected, negated-hole, and real-consumer end-to-end fixtures**. A detector of "is the user's config adequate" needs both directions, or the vacuous case hides the bug.
+- **Formatter hazard (consumer-fatal):** a repo-wide Prettier run over sync-managed files rewrites their hashes and is by itself sufficient to **permanently freeze** a consumer's updates. `.prettierignore` must be established **before** formatting, not added after the damage. Ship it, scaffold it if absent, and warn once when an existing one is inadequate.
+
+**Agent tuning notes:**
+- **implementer / coder**: asking an implementing agent to **pause when a heuristic exceeds a stated complexity threshold** produced an honest escalation instead of a silently wrong heuristic. Worth repeating for any "detect whether the user's config is adequate" feature: state the threshold up front and treat pausing as success, not failure.
+- **reviewer (two-round shape)**: round 1 caught missing user-facing coverage; round 2 blocked the *new* mechanism for being wrong in both directions. A fix that introduces a heuristic deserves a dedicated review pass — reviewing it as part of the original change under-weights it.
+- **coder (docs for honest gaps)**: protect-but-don't-honour (`.agents-sync-ignore`) must be stated plainly in the README and in code comments. Shipping the storage without the semantics is acceptable only when it is impossible to mistake for working.
+- **all agents (knowledge retrieval)**: `memory_search` executed (cwd-scoped to this repo); `knowledgebase_search` **NOT executed** (PG vector unavailable — `DATABASE_URL` not configured). Neither retried nor treated as a task failure.

package/.prettierignore

@@ -0,0 +1,26 @@
+# Project-owned. Sync never overwrites this file.
+# Keep formatters away from files managed by @abarcenas/ai-workflow-template:
+# a formatting pass over managed files makes every future sync skip them.
+
+# Managed agent configuration
+.agents/
+.opencode/agents/
+.opencode/commands/
+
+# Managed root files
+AGENTS.md
+AGENTS.project.md
+skills-lock.json
+
+# Managed scripts (scripts/sync.js scriptsToSync)
+scripts/memory-cli.js
+scripts/memory-index.js
+scripts/bump-version.js
+scripts/validate-memory-schema.js
+scripts/vocab-sync.js
+scripts/mcp-memory-server.js
+scripts/mcp/playwright-mcp-launcher.js
+scripts/knowledgebase-cli.js
+scripts/knowledgebase-index.js
+scripts/mcp-knowledgebase-server.js
+scripts/knowledgebase-init.sql

package/AGENTS.md

@@ -9,6 +9,10 @@ This project includes AI-assisted development configuration distributed through
 - `.opencode/agents/` — Specialized agent definitions for planning, research, and implementation
 - `.agents/prompts/` — Reusable prompt templates
 
+## Project-Specific Rules
+
+Put project-specific agent rules in `AGENTS.project.md` at the repository root. That file is project-owned: sync never overwrites or prunes it, and `--force` cannot replace it. New projects load it automatically through the `instructions` entry in `opencode.json`.
+
 ## Core Workflow
 
 1. **Understand before acting** — Read relevant instructions from `.agents/instructions/` before working with specific technologies

package/README.md

@@ -75,8 +75,29 @@ npm run sync                # Normal sync
 - New files are copied automatically
 - Unmodified files are refreshed from the package
 - Locally edited files are preserved (skipped by default)
+- Project-owned files are never overwritten or pruned after creation, and `--force` cannot replace them
 - GitHub Actions workflows are excluded from consumer sync (`.github/workflows/`)
 
+> `--dry-run` previews copies and prunes, but missing scaffold files (memory-bank stubs, `opencode.json`, `AGENTS.project.md`, `.prettierignore`) are still created. This matches the pre-existing scaffold behaviour.
+
+### Project-owned files
+
+`AGENTS.project.md` is the supported home for project-specific agent rules. It is created if absent, then treated as project-owned: sync never overwrites or prunes it, `--force` cannot replace it, and deleting it recreates it on the next sync. New projects load it through `"instructions": ["AGENTS.project.md"]` in `opencode.json`; a project created before that entry existed must add it once, because sync never rewrites an existing `opencode.json`.
+
+The same ownership rule protects `opencode.json`, `.prettierignore`, and `.agents/instructions/learned-knowledge.instructions.md`. `.agents-sync-ignore` is also protected from overwrite and deletion, but sync does **not** read or honour its contents yet — do not rely on it.
+
+`__project__/<file>` entries in `.agents-sync-manifest.json` are reporting metadata written only when sync creates the file. Files that already existed before the upgrade are intentionally absent, because sync has no managed baseline for them.
+
+The package ships a `.prettierignore` and scaffolds it when absent. New projects get coverage automatically for `.agents/`, `.opencode/agents/`, `.opencode/commands/`, `AGENTS.md`, `skills-lock.json`, and every synced script; the shipped file also ignores `AGENTS.project.md`, though that file is not hash-managed. Existing projects keep their own `.prettierignore` untouched (it is project-owned), so if it does not cover every managed path sync prints one warning:
+
+```text
+[ai-workflow-template] Existing .prettierignore does not protect managed files; merge the patterns from node_modules/@abarcenas/ai-workflow-template/.prettierignore
+```
+
+Merge those patterns manually — sync never edits the file. Template-side additions to `rootFiles` or `scriptsToSync` also require a matching manual line in an existing project; the shipped file only updates the defaults for new projects. A formatter run over managed files rewrites their hashes, so every later sync skips them and the consumer stops receiving template updates.
+
+If sync warns `Skipped locally modified root file: AGENTS.md`, move those local rules into `AGENTS.project.md`, restore the managed file from `node_modules/@abarcenas/ai-workflow-template/AGENTS.md`, then re-run sync.
+
 ## Core Structure
 
 Post-install, your project receives this structure:
@@ -90,6 +111,7 @@ Post-install, your project receives this structure:
 .github/workflows/  # CI/CD automation (excluded from sync)
 docs/               # Guides (e.g. playwright-mcp-configuration.md)
 AGENTS.md           # Master instruction file with agent guidance
+AGENTS.project.md   # Project-owned rules (recreated if deleted, never overwritten)
 ```
 
 ## Multi-Agent Orchestrator
@@ -286,6 +308,8 @@ npm run memory:normalize   # Normalize frontmatter (runs automatically on instal
 
 - Uses `INIT_CWD` to install against the consuming project (not the package dir)
 - Local changes are always preserved unless `--force` is used
+- Project-owned files (`AGENTS.project.md`, `opencode.json`, `.prettierignore`, learned knowledge) are created if absent and never overwritten or pruned after that, even with `--force`
+- Do not add `AGENTS.project.md` or `opencode.json` to `package.json` `files`: both are scaffolded create-if-absent and must never ship from the package
 - `AGENTS.md` is the main instruction file agents should read
 - Package assumes the public npm registry
 - Playwright MCP integration is documented in `docs/`

package/opencode.mcp.example.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "instructions": ["AGENTS.project.md"],
   "mcp": {
     "chrome-devtools": {
       "type": "local",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.46.0",
+  "version": "1.47.0",
   "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
   "main": "index.js",
   "bin": {
@@ -38,6 +38,7 @@
     "url": "https://github.com/abarcenas29/ai-workflow-template/issues"
   },
   "homepage": "https://github.com/abarcenas29/ai-workflow-template#readme",
+  "//": "Never add AGENTS.project.md or opencode.json to files: both are scaffolded create-if-absent at the consumer root and must not ship from the package.",
   "files": [
     "bin/",
     ".agents/",
@@ -49,6 +50,7 @@
     ".husky/",
     "memory-bank/.vocabulary.json",
     "AGENTS.md",
+    ".prettierignore",
     "opencode.mcp.example.json",
     "skills-lock.json",
     ".husky/post-merge",

package/scripts/sync-unit.test.js

@@ -9,6 +9,7 @@
 // ═════════════════════════════════════════════════════════════════════════════
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { spawnSync } from 'child_process'
 import { createHash } from 'crypto'
 import {
   chmodSync,
@@ -21,7 +22,7 @@ import {
   symlinkSync,
   writeFileSync,
 } from 'fs'
-import { dirname, join } from 'path'
+import { dirname, join, resolve } from 'path'
 import { tmpdir } from 'os'
 import { fileURLToPath } from 'url'
 
@@ -35,13 +36,22 @@ import {
   isRegularFile,
   isUntouched,
   memoryBankStubs,
+  missingPrettierIgnorePatterns,
   parseArgs,
+  parsePrettierIgnoreRules,
+  projectOwnedPaths,
+  projectOwnedStubs,
   readManifest,
+  requiredPrettierIgnorePatterns,
   resolvePruneEntry,
+  rootFiles,
   runSync,
+  scriptsToSync,
   writeManifest,
 } from './sync.js'
 
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
 const tempDirs = []
 
 function createTempDir() {
@@ -588,22 +598,32 @@ describe('resolvePruneEntry', () => {
     )
   })
 
-  it('keeps opencode.json alive via the example fallback source', () => {
+  it('never resolves project-owned files as prune entries', () => {
     const ctx = context()
 
-    const entry = resolvePruneEntry('__root__/opencode.json', ctx)
-
-    expect(entry.packagePaths).toEqual([
-      join(ctx.packageRoot, 'opencode.json'),
-      join(ctx.packageRoot, 'opencode.mcp.example.json'),
-    ])
+    for (const key of [
+      '__root__/AGENTS.project.md',
+      '__root__/opencode.json',
+      '__root__/.prettierignore',
+      '__root__/.agents-sync-ignore',
+      'instructions/learned-knowledge.instructions.md',
+      '__project__/AGENTS.project.md',
+      '__project__/.prettierignore',
+    ]) {
+      expect(resolvePruneEntry(key, ctx), key).toBeNull()
+    }
   })
 
   it.each([
     ['unknown internal namespace', '__future__/thing.md'],
+    ['scaffold-only project namespace', '__project__/AGENTS.project.md'],
     ['scaffold-only memory-bank namespace', '__memory-bank__/projectbrief.md'],
     ['scaffold-only instructions namespace', '__agents-instructions__/x.md'],
     ['excluded learned-knowledge file', 'instructions/learned-knowledge.instructions.md'],
+    ['project-owned root AGENTS.project.md', '__root__/AGENTS.project.md'],
+    ['project-owned root opencode.json', '__root__/opencode.json'],
+    ['project-owned root .prettierignore', '__root__/.prettierignore'],
+    ['project-owned root .agents-sync-ignore', '__root__/.agents-sync-ignore'],
     ['excluded opencode node_modules path', '__opencode__/node_modules/dep.js'],
     ['excluded opencode package.json', '__opencode__/package.json'],
     ['empty opencode key', '__opencode__/'],
@@ -664,7 +684,7 @@ describe('runSync copy passes', () => {
     expect(result.exitCode).toBe(0)
     expect(result.copied).toBe(9)
     expect(result.added).toBe(9)
-    expect(result.scaffolded).toBe(8)
+    expect(result.scaffolded).toBe(10)
     expect(result.skipped).toBe(0)
     expect(errorSpy).not.toHaveBeenCalled()
 
@@ -757,12 +777,21 @@ describe('runSync copy passes', () => {
     expect(manifest.files['__root__/AGENTS.md']).toBe(
       sha256(ROOT_FILE_CONTENTS['AGENTS.md']),
     )
-    expect(manifest.files['__root__/opencode.json']).toBe(sha256(MCP_EXAMPLE))
+    expect(manifest.files['__project__/opencode.json']).toBe(sha256(MCP_EXAMPLE))
+    expect(manifest.files['__root__/opencode.json']).toBeUndefined()
     expect(
       manifest.files['__agents-instructions__/learned-knowledge.instructions.md'],
     ).toBe(
       sha256(agentInstructionsStubs['learned-knowledge.instructions.md']),
     )
+    expect(manifest.files['__project__/AGENTS.project.md']).toBe(
+      sha256(projectOwnedStubs['AGENTS.project.md']),
+    )
+    expect(manifest.files['__project__/.prettierignore']).toBe(
+      sha256(projectOwnedStubs['.prettierignore']),
+    )
+    expect(manifest.files['__root__/AGENTS.project.md']).toBeUndefined()
+    expect(manifest.files['__root__/.prettierignore']).toBeUndefined()
     for (const fileName of Object.keys(memoryBankStubs)) {
       expect(manifest.files[`__memory-bank__/${fileName}`]).toBeDefined()
     }
@@ -866,7 +895,7 @@ describe('runSync copy passes', () => {
     expect(outputOf(logSpy)).toContain('Mode: force.')
   })
 
-  it('prefers a package-shipped opencode.json over the example file', () => {
+  it('never adopts a package-shipped opencode.json: the example scaffold wins', () => {
     const packageRoot = createPackage({
       agents: {},
       root: { 'opencode.json': '{ "mcp": { "from": "package" } }\n' },
@@ -876,8 +905,10 @@ describe('runSync copy passes', () => {
 
     runSync({ packageRoot, consumerRoot })
 
+    // opencode.json is project-owned, so the root copy pass skips it and the
+    // create-if-absent scaffold from the shipped example is what lands.
     expect(readFileSync(join(consumerRoot, 'opencode.json'), 'utf8')).toBe(
-      '{ "mcp": { "from": "package" } }\n',
+      MCP_EXAMPLE,
     )
   })
 
@@ -982,6 +1013,514 @@ describe('runSync copy passes', () => {
   })
 })
 
+// ── Project-owned files ──────────────────────────────────────────────────────
+
+const PROJECT_OWNED_LOCAL_CONTENT = {
+  'AGENTS.project.md': '# Local project rules\n\n- never overwrite this',
+  'opencode.json': '{ "local": true }\n',
+  '.prettierignore': 'my-build/\n',
+  '.agents-sync-ignore': '# local ignore rules\n',
+  '.agents/instructions/learned-knowledge.instructions.md': '# Local knowledge\n',
+}
+
+const LEGACY_PRETTIER_IGNORE =
+  '/dist\n/coverage\n/.nx/cache\n/.nx/workspace-data\n'
+
+const PRETTIER_IGNORE_WARNING =
+  '[ai-workflow-template] Existing .prettierignore does not protect managed files; merge the patterns from node_modules/@abarcenas/ai-workflow-template/.prettierignore'
+
+const COMPLETE_PRETTIER_IGNORE = [
+  '.agents/',
+  '.opencode/',
+  'scripts/',
+  'AGENTS.md',
+  'skills-lock.json',
+].join('\n')
+
+// B1 coverage matrix: parent-directory coverage, negation holes, strict
+// descendants, comments, inline literals, normalisation and ignore-all forms.
+const PRETTIER_IGNORE_MATRIX = [
+  ['exact shipped content', projectOwnedStubs['.prettierignore'], false],
+  ['parent directories cover descendants', COMPLETE_PRETTIER_IGNORE, false],
+  [
+    'shipped without AGENTS.md',
+    projectOwnedStubs['.prettierignore'].replace('\nAGENTS.md\n', '\n'),
+    true,
+  ],
+  [
+    'negation hole below .agents/',
+    [
+      '.agents/',
+      '!.agents/skills/**',
+      '.opencode/',
+      'scripts/',
+      'AGENTS.md',
+      'skills-lock.json',
+    ].join('\n'),
+    true,
+  ],
+  [
+    'later positive restores a negated subtree',
+    [
+      '.agents/',
+      '!.agents/skills/**',
+      '.agents/skills/',
+      '.opencode/',
+      'scripts/',
+      'AGENTS.md',
+      'skills-lock.json',
+    ].join('\n'),
+    false,
+  ],
+  [
+    'AGENTS.md/** does not cover the file',
+    COMPLETE_PRETTIER_IGNORE.replace('AGENTS.md', 'AGENTS.md/**'),
+    true,
+  ],
+  [
+    '.agents without a trailing slash',
+    COMPLETE_PRETTIER_IGNORE.replace('.agents/', '.agents'),
+    false,
+  ],
+  [
+    'commented-out .agents/',
+    COMPLETE_PRETTIER_IGNORE.replace('.agents/', '# .agents/'),
+    true,
+  ],
+  [
+    'leading **/ wildcard',
+    COMPLETE_PRETTIER_IGNORE.replace('AGENTS.md', '**/AGENTS.md'),
+    false,
+  ],
+  [
+    'inline hash is literal',
+    COMPLETE_PRETTIER_IGNORE.replace('AGENTS.md', 'AGENTS.md # managed'),
+    true,
+  ],
+  [
+    'CRLF and trailing spaces',
+    COMPLETE_PRETTIER_IGNORE.split('\n')
+      .map((line) => `${line}  `)
+      .join('\r\n'),
+    false,
+  ],
+  [
+    'leading-slash patterns (including /dist)',
+    ['/dist', '/.agents/', '/.opencode/', '/scripts/', '/AGENTS.md', '/skills-lock.json'].join(
+      '\n',
+    ),
+    false,
+  ],
+  ['* ignores everything', '*', false],
+  ['** ignores everything', '**', false],
+]
+
+function createProjectOwnedFixture() {
+  // The package ships competing copies at the project-owned paths. None may win.
+  const packageRoot = createPackage({
+    agents: {
+      'instructions/learned-knowledge.instructions.md': '# Package knowledge\n',
+    },
+    root: {
+      'AGENTS.project.md': '# Package rules\n',
+      'opencode.json': '{ "package": true }\n',
+      '.prettierignore': 'package-build/\n',
+      '.agents-sync-ignore': '# package ignore\n',
+    },
+    mcpExample: MCP_EXAMPLE,
+  })
+  const consumerRoot = createTempDir()
+
+  for (const [relativePath, contents] of Object.entries(
+    PROJECT_OWNED_LOCAL_CONTENT,
+  )) {
+    writeFixtureFile(consumerRoot, relativePath, contents)
+  }
+
+  return { packageRoot, consumerRoot }
+}
+
+describe('project-owned files', () => {
+  it('scaffolds AGENTS.project.md and .prettierignore create-if-absent', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+
+    const result = runSync({ packageRoot, consumerRoot })
+
+    expect(result.scaffolded).toBe(10)
+    expect(readFileSync(join(consumerRoot, 'AGENTS.project.md'), 'utf8')).toBe(
+      projectOwnedStubs['AGENTS.project.md'],
+    )
+    expect(readFileSync(join(consumerRoot, '.prettierignore'), 'utf8')).toBe(
+      projectOwnedStubs['.prettierignore'],
+    )
+
+    const manifest = readConsumerManifest(consumerRoot)
+    expect(manifest.files['__project__/AGENTS.project.md']).toBe(
+      sha256(projectOwnedStubs['AGENTS.project.md']),
+    )
+    expect(manifest.files['__project__/.prettierignore']).toBe(
+      sha256(projectOwnedStubs['.prettierignore']),
+    )
+    // Ownership is reported through __project__, never through a sync channel.
+    expect(manifest.files['__root__/AGENTS.project.md']).toBeUndefined()
+    expect(manifest.files['__root__/.prettierignore']).toBeUndefined()
+  })
+
+  it('does not overwrite existing project-owned files, even with --force', () => {
+    const { packageRoot, consumerRoot } = createProjectOwnedFixture()
+
+    const result = runSync({
+      packageRoot,
+      consumerRoot,
+      argv: ['--force'],
+      env: {},
+    })
+
+    expect(result.skipped).toBe(0)
+    for (const [relativePath, contents] of Object.entries(
+      PROJECT_OWNED_LOCAL_CONTENT,
+    )) {
+      expect(
+        readFileSync(join(consumerRoot, relativePath), 'utf8'),
+        relativePath,
+      ).toBe(contents)
+    }
+
+    const manifest = readConsumerManifest(consumerRoot)
+    for (const key of [
+      '__root__/AGENTS.project.md',
+      '__root__/opencode.json',
+      '__root__/.prettierignore',
+      '__root__/.agents-sync-ignore',
+      '__project__/AGENTS.project.md',
+      '__project__/.prettierignore',
+      '__project__/opencode.json',
+    ]) {
+      expect(manifest.files[key], key).toBeUndefined()
+    }
+  })
+
+  it('preserves a local AGENTS.project.md edit byte-for-byte across a sync', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+
+    runSync({ packageRoot, consumerRoot })
+    const localEdit = '# Project rules\n\n- local edit, no trailing newline'
+    writeFixtureFile(consumerRoot, 'AGENTS.project.md', localEdit)
+
+    const result = runSync({
+      packageRoot,
+      consumerRoot,
+      argv: ['--force'],
+      env: {},
+    })
+
+    expect(result.skipped).toBe(0)
+    expect(readFileSync(join(consumerRoot, 'AGENTS.project.md'), 'utf8')).toBe(
+      localEdit,
+    )
+  })
+
+  it('never clobbers an existing consumer .prettierignore', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+    const localIgnore = 'coverage/\nplaywright-report/\n'
+    writeFixtureFile(consumerRoot, '.prettierignore', localIgnore)
+
+    runSync({ packageRoot, consumerRoot })
+    runSync({ packageRoot, consumerRoot, argv: ['--force'], env: {} })
+
+    expect(readFileSync(join(consumerRoot, '.prettierignore'), 'utf8')).toBe(
+      localIgnore,
+    )
+    expect(
+      readConsumerManifest(consumerRoot).files['__project__/.prettierignore'],
+    ).toBeUndefined()
+  })
+
+  it('warns once when an existing .prettierignore does not protect managed files', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+    writeFixtureFile(consumerRoot, '.prettierignore', LEGACY_PRETTIER_IGNORE)
+
+    const result = runSync({ packageRoot, consumerRoot })
+
+    expect(result.scaffolded).toBe(9)
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(outputOf(warnSpy)).toBe(PRETTIER_IGNORE_WARNING)
+    // Warning only: the consumer file is byte-for-byte unchanged.
+    expect(readFileSync(join(consumerRoot, '.prettierignore'), 'utf8')).toBe(
+      LEGACY_PRETTIER_IGNORE,
+    )
+  })
+
+  it.skipIf(process.getuid?.() === 0)(
+    'skips the advisory when .prettierignore cannot be read',
+    () => {
+      const { packageRoot, consumerRoot } = createCopyFixture()
+      const ignorePath = writeFixtureFile(
+        consumerRoot,
+        '.prettierignore',
+        LEGACY_PRETTIER_IGNORE,
+      )
+      chmodSync(ignorePath, 0o000)
+
+      try {
+        const result = runSync({ packageRoot, consumerRoot })
+
+        expect(result.exitCode).toBe(0)
+        expect(warnSpy).not.toHaveBeenCalled()
+        expect(existsSync(join(consumerRoot, '.agents-sync-manifest.json'))).toBe(
+          true,
+        )
+      } finally {
+        chmodSync(ignorePath, 0o644)
+      }
+    },
+  )
+
+  it('does not warn when an existing .prettierignore covers managed files', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+    writeFixtureFile(
+      consumerRoot,
+      '.prettierignore',
+      projectOwnedStubs['.prettierignore'],
+    )
+
+    runSync({ packageRoot, consumerRoot })
+
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('does not warn when .prettierignore was just scaffolded', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+
+    runSync({ packageRoot, consumerRoot })
+
+    expect(warnSpy).not.toHaveBeenCalled()
+    expect(readFileSync(join(consumerRoot, '.prettierignore'), 'utf8')).toBe(
+      projectOwnedStubs['.prettierignore'],
+    )
+  })
+
+  // Pins current behaviour: scaffolding is not gated by --dry-run. Update this
+  // test when scaffolding becomes dry-run aware.
+  it('documents that --dry-run still scaffolds missing project-owned files', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+
+    const result = runSync({
+      packageRoot,
+      consumerRoot,
+      argv: ['--dry-run'],
+      env: {},
+    })
+
+    expect(result.scaffolded).toBe(10)
+    expect(readFileSync(join(consumerRoot, 'AGENTS.project.md'), 'utf8')).toBe(
+      projectOwnedStubs['AGENTS.project.md'],
+    )
+    expect(readFileSync(join(consumerRoot, '.prettierignore'), 'utf8')).toBe(
+      projectOwnedStubs['.prettierignore'],
+    )
+    expect(existsSync(join(consumerRoot, '.agents-sync-manifest.json'))).toBe(
+      false,
+    )
+  })
+
+  it('does not refresh __project__ hashes after a consumer edit', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+
+    runSync({ packageRoot, consumerRoot })
+    const originalHash = readConsumerManifest(consumerRoot).files[
+      '__project__/AGENTS.project.md'
+    ]
+    writeFixtureFile(consumerRoot, 'AGENTS.project.md', '# edited locally\n')
+
+    runSync({ packageRoot, consumerRoot, argv: ['--force'], env: {} })
+
+    expect(
+      readConsumerManifest(consumerRoot).files['__project__/AGENTS.project.md'],
+    ).toBe(originalHash)
+  })
+
+  it('does not throw when a project-owned scaffold path is a directory', () => {
+    const { packageRoot, consumerRoot } = createCopyFixture()
+    mkdirSync(join(consumerRoot, 'AGENTS.project.md'), { recursive: true })
+    mkdirSync(join(consumerRoot, '.prettierignore'), { recursive: true })
+
+    const result = runSync({ packageRoot, consumerRoot })
+
+    expect(result.exitCode).toBe(0)
+    expect(existsSync(join(consumerRoot, '.agents-sync-manifest.json'))).toBe(
+      true,
+    )
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('never prunes any project-owned path, including with --prune', () => {
+    const packageRoot = createPackage({ agents: {} })
+    const consumerRoot = createTempDir()
+
+    for (const [relativePath, contents] of Object.entries(
+      PROJECT_OWNED_LOCAL_CONTENT,
+    )) {
+      writeFixtureFile(consumerRoot, relativePath, contents)
+    }
+
+    const trackedKeys = {
+      '__root__/AGENTS.project.md': 'AGENTS.project.md',
+      '__root__/opencode.json': 'opencode.json',
+      '__root__/.prettierignore': '.prettierignore',
+      '__root__/.agents-sync-ignore': '.agents-sync-ignore',
+      'instructions/learned-knowledge.instructions.md':
+        '.agents/instructions/learned-knowledge.instructions.md',
+      '__project__/AGENTS.project.md': 'AGENTS.project.md',
+      '__project__/.prettierignore': '.prettierignore',
+    }
+    writeManifest(
+      join(consumerRoot, '.agents-sync-manifest.json'),
+      {
+        version: 1,
+        files: Object.fromEntries(
+          Object.entries(trackedKeys).map(([key, relativePath]) => [
+            key,
+            sha256(PROJECT_OWNED_LOCAL_CONTENT[relativePath]),
+          ]),
+        ),
+      },
+    )
+
+    const result = runSync({
+      packageRoot,
+      consumerRoot,
+      argv: ['--prune', '--force'],
+      env: {},
+    })
+
+    expect(result.pruned).toBe(0)
+    for (const [relativePath, contents] of Object.entries(
+      PROJECT_OWNED_LOCAL_CONTENT,
+    )) {
+      expect(
+        readFileSync(join(consumerRoot, relativePath), 'utf8'),
+        relativePath,
+      ).toBe(contents)
+    }
+
+    const manifest = readConsumerManifest(consumerRoot)
+    for (const key of Object.keys(trackedKeys)) {
+      expect(manifest.files, key).toHaveProperty([key])
+    }
+  })
+
+  it('keeps the shipped .prettierignore covering every managed root file and script', () => {
+    const shipped = readFileSync(join(repoRoot, '.prettierignore'), 'utf8')
+
+    expect(shipped).toBe(projectOwnedStubs['.prettierignore'])
+    expect(missingPrettierIgnorePatterns(shipped)).toEqual([])
+
+    for (const rootFile of rootFiles) {
+      expect(
+        missingPrettierIgnorePatterns(shipped, [rootFile]),
+        rootFile,
+      ).toEqual([])
+    }
+    for (const script of scriptsToSync) {
+      const pattern = `scripts/${script}`
+      expect(
+        missingPrettierIgnorePatterns(shipped, [pattern]),
+        pattern,
+      ).toEqual([])
+    }
+  })
+
+  it.each(PRETTIER_IGNORE_MATRIX)(
+    'detects coverage correctly: %s',
+    (_label, contents, expectWarning) => {
+      const { packageRoot, consumerRoot } = createCopyFixture()
+      writeFixtureFile(consumerRoot, '.prettierignore', contents)
+
+      runSync({ packageRoot, consumerRoot })
+
+      expect(
+        missingPrettierIgnorePatterns(contents).length > 0,
+        'detector result',
+      ).toBe(expectWarning)
+      if (expectWarning) {
+        expect(warnSpy).toHaveBeenCalledTimes(1)
+        expect(outputOf(warnSpy)).toBe(PRETTIER_IGNORE_WARNING)
+      } else {
+        expect(warnSpy).not.toHaveBeenCalled()
+      }
+    },
+  )
+
+  it('parses gitignore comments, negations and escaped markers', () => {
+    expect(
+      parsePrettierIgnoreRules(
+        '# comment\n!AGENTS.md\n\\#literal\n\\!literal\nAGENTS.md # inline\n',
+      ),
+    ).toEqual([
+      { negated: true, pattern: 'AGENTS.md' },
+      { negated: false, pattern: '#literal' },
+      { negated: false, pattern: '!literal' },
+      { negated: false, pattern: 'AGENTS.md # inline' },
+    ])
+  })
+
+  it('ships an opencode example that loads AGENTS.project.md', () => {
+    const example = JSON.parse(
+      readFileSync(join(repoRoot, 'opencode.mcp.example.json'), 'utf8'),
+    )
+
+    expect(example.instructions).toEqual(['AGENTS.project.md'])
+  })
+
+  it('scaffolds opencode.json with the project instructions entry', () => {
+    const example = readFileSync(
+      join(repoRoot, 'opencode.mcp.example.json'),
+      'utf8',
+    )
+    const packageRoot = createPackage({ agents: {}, mcpExample: example })
+    const consumerRoot = createTempDir()
+
+    runSync({ packageRoot, consumerRoot })
+
+    const config = JSON.parse(
+      readFileSync(join(consumerRoot, 'opencode.json'), 'utf8'),
+    )
+    expect(config.instructions).toEqual(['AGENTS.project.md'])
+  })
+
+  it('does not ship project-owned files in the npm package', () => {
+    const packageManifest = JSON.parse(
+      readFileSync(join(repoRoot, 'package.json'), 'utf8'),
+    )
+    expect(packageManifest.files).not.toContain('AGENTS.project.md')
+    expect(packageManifest.files).not.toContain('opencode.json')
+    expect(packageManifest.files).toContain('.prettierignore')
+
+    const packed = spawnSync('npm', ['pack', '--dry-run', '--json'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    })
+    expect(packed.status).toBe(0)
+    const files = JSON.parse(packed.stdout)[0].files.map((file) => file.path)
+    expect(files).toContain('.prettierignore')
+    expect(files).not.toContain('AGENTS.project.md')
+    expect(files).not.toContain('opencode.json')
+  })
+
+  it('reserves every documented project-owned path', () => {
+    for (const relativePath of [
+      'AGENTS.project.md',
+      'opencode.json',
+      '.prettierignore',
+      '.agents-sync-ignore',
+      'instructions/learned-knowledge.instructions.md',
+    ]) {
+      expect(projectOwnedPaths.has(relativePath), relativePath).toBe(true)
+    }
+  })
+})
+
 // ── Prune decisions ──────────────────────────────────────────────────────────
 
 const PRUNE_CONTENT = {

package/scripts/sync.js

@@ -19,6 +19,27 @@ export const excludedRelativePaths = new Set([
   'instructions/learned-knowledge.instructions.md',
 ])
 
+// Files the consumer owns outright. Sync never copies, overwrites, or prunes
+// them — not even with --force — because local edits are the point, not drift.
+// Matching is channel-agnostic: every copy pass compares its own relative path
+// against this set, so a root entry such as "opencode.json" also protects
+// ".opencode/opencode.json" and ".agents/opencode.json". That over-match is
+// intentional and conservative. The original learned-knowledge exclusion is
+// spread in so there is one rule, not two parallel checks.
+export const projectOwnedPaths = new Set([
+  'AGENTS.project.md',
+  'opencode.json',
+  '.prettierignore',
+  // Reserved: sync protects this file from overwrite and prune, but it does
+  // NOT read or honour its globs yet. Do not present it as functional.
+  '.agents-sync-ignore',
+  ...excludedRelativePaths,
+])
+
+export function isProjectOwnedPath(relativePath) {
+  return projectOwnedPaths.has(relativePath)
+}
+
 export const openCodeExcluded = new Set([
   'node_modules',
   'package.json',
@@ -27,7 +48,10 @@ export const openCodeExcluded = new Set([
   '.gitignore',
 ])
 
-export const rootFiles = ['AGENTS.md', 'opencode.json', 'skills-lock.json']
+// Never add a project-owned file here (AGENTS.project.md, opencode.json,
+// .prettierignore): those are scaffolded create-if-absent and must not ship
+// from the package. opencode.json is governed solely by projectOwnedPaths.
+export const rootFiles = ['AGENTS.md', 'skills-lock.json']
 
 export const scriptsToSync = [
   'memory-cli.js',
@@ -44,6 +68,153 @@ export const scriptsToSync = [
   'knowledgebase-init.sql',
 ]
 
+// The hash-managed paths a consumer's .prettierignore must cover so a format
+// pass cannot freeze a sync. Directories carry a trailing slash so a pattern
+// can cover their subtree. AGENTS.project.md is deliberately absent: it is
+// project-owned, so formatting it cannot freeze a sync.
+export const requiredPrettierIgnorePatterns = [
+  '.agents/',
+  '.opencode/agents/',
+  '.opencode/commands/',
+  ...rootFiles,
+  ...scriptsToSync.map((script) => `scripts/${script}`),
+]
+
+const prettierIgnoreWarning =
+  '[ai-workflow-template] Existing .prettierignore does not protect managed files; merge the patterns from node_modules/@abarcenas/ai-workflow-template/.prettierignore'
+
+const ignoreAllPatterns = new Set(['', '.', '*', '**', '/'])
+
+function normalizeIgnorePattern(pattern) {
+  const trimmed = pattern.trim()
+  return trimmed === '/'
+    ? '/'
+    : trimmed.replace(/^\/+/, '').replace(/\/+$/, '')
+}
+
+// Gitignore lines, preserving negation and treating an inline "# ..." literally.
+// Escaped leading "#" or "!" are literals, not comments/negations.
+export function parsePrettierIgnoreRules(contents) {
+  const rules = []
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) {
+      continue
+    }
+
+    if (line.startsWith('\\#') || line.startsWith('\\!')) {
+      rules.push({
+        negated: false,
+        pattern: normalizeIgnorePattern(line.slice(1)),
+      })
+      continue
+    }
+
+    const negated = line.startsWith('!')
+    const pattern = normalizeIgnorePattern(negated ? line.slice(1) : line)
+    if (pattern) {
+      rules.push({ negated, pattern })
+    }
+  }
+
+  return rules
+}
+
+// True when a pattern ignores targetPath or one of its ancestors. A "base/**"
+// pattern ignores strict descendants only, so it never covers the file "base".
+function patternAppliesTo(pattern, targetPath) {
+  if (ignoreAllPatterns.has(pattern)) {
+    return true
+  }
+  if (pattern.endsWith('/**')) {
+    return targetPath.startsWith(`${pattern.slice(0, -3)}/`)
+  }
+  if (pattern.startsWith('**/')) {
+    const suffix = pattern.slice(3)
+    return targetPath === suffix || targetPath.endsWith(`/${suffix}`)
+  }
+  if (/[*?[]/.test(pattern)) {
+    return false
+  }
+  return targetPath === pattern || targetPath.startsWith(`${pattern}/`)
+}
+
+// A negation below a managed directory punches a hole in that directory's
+// subtree, so it removes coverage until a later positive restores the subtree.
+function ignorePatternBase(pattern) {
+  return normalizeIgnorePattern(
+    pattern.endsWith('/**') ? pattern.slice(0, -3) : pattern,
+  )
+}
+
+function patternAppliesBelow(pattern, directoryPath) {
+  if (ignoreAllPatterns.has(pattern)) {
+    return true
+  }
+
+  const base = ignorePatternBase(pattern)
+  return (
+    !/[*?[]/.test(base) &&
+    base.startsWith(directoryPath) &&
+    base !== normalizeIgnorePattern(directoryPath)
+  )
+}
+
+// Last-match-wins over the rule list, matching gitignore semantics. Required
+// directories also track negated subtrees so a later positive can restore them.
+function isCovered(requiredPath, rules) {
+  const isDirectory = requiredPath.endsWith('/')
+  let covered = false
+  const holes = new Set()
+
+  for (const { negated, pattern } of rules) {
+    if (!isDirectory) {
+      if (patternAppliesTo(pattern, requiredPath)) {
+        covered = !negated
+      }
+      continue
+    }
+
+    if (negated) {
+      if (patternAppliesTo(pattern, requiredPath)) {
+        covered = false
+        holes.clear()
+      } else if (patternAppliesBelow(pattern, requiredPath)) {
+        holes.add(ignorePatternBase(pattern))
+      }
+      continue
+    }
+
+    if (patternAppliesTo(pattern, requiredPath)) {
+      covered = true
+      holes.clear()
+      continue
+    }
+
+    if (patternAppliesBelow(pattern, requiredPath)) {
+      const base = ignorePatternBase(pattern)
+      for (const hole of holes) {
+        if (hole === base || hole.startsWith(`${base}/`)) {
+          holes.delete(hole)
+        }
+      }
+    }
+  }
+
+  return covered && holes.size === 0
+}
+
+export function missingPrettierIgnorePatterns(
+  contents,
+  requiredPatterns = requiredPrettierIgnorePatterns,
+) {
+  const rules = parsePrettierIgnoreRules(contents)
+  return requiredPatterns.filter(
+    (requiredPath) => !isCovered(requiredPath, rules),
+  )
+}
+
 export const memoryBankStubs = {
   'projectbrief.md': `# projectbrief
 
@@ -106,6 +277,49 @@ Cross-session knowledge accumulated by agent pipelines. Each session records dis
 `,
 }
 
+// Project-owned files are scaffolded create-if-absent and then left alone for
+// the lifetime of the consumer project (deleting one recreates it on the next
+// sync). The .prettierignore text here must stay byte-identical to the
+// repository's shipped .prettierignore (asserted in sync-unit.test.js) so the
+// tarball copy and the scaffold cannot drift.
+export const projectOwnedStubs = {
+  'AGENTS.project.md': `# Project Rules
+
+> Project-owned. This file is never overwritten or pruned by sync — edit it freely.
+
+## Project-specific agent rules
+
+- {{add project-specific rules here}}
+`,
+  '.prettierignore': `# Project-owned. Sync never overwrites this file.
+# Keep formatters away from files managed by @abarcenas/ai-workflow-template:
+# a formatting pass over managed files makes every future sync skip them.
+
+# Managed agent configuration
+.agents/
+.opencode/agents/
+.opencode/commands/
+
+# Managed root files
+AGENTS.md
+AGENTS.project.md
+skills-lock.json
+
+# Managed scripts (scripts/sync.js scriptsToSync)
+scripts/memory-cli.js
+scripts/memory-index.js
+scripts/bump-version.js
+scripts/validate-memory-schema.js
+scripts/vocab-sync.js
+scripts/mcp-memory-server.js
+scripts/mcp/playwright-mcp-launcher.js
+scripts/knowledgebase-cli.js
+scripts/knowledgebase-index.js
+scripts/mcp-knowledgebase-server.js
+scripts/knowledgebase-init.sql
+`,
+}
+
 // Parses the flags supported by the sync entry point. Unknown flags are ignored
 // so that consumer tooling can pass extra arguments without breaking a sync.
 export function parseArgs(argv = [], env = process.env) {
@@ -263,10 +477,16 @@ export function isPathInside(baseDir, candidatePath) {
 // Resolves a manifest key to its package path (for the "still shipped?" check)
 // and its consumer path (the prune candidate). Returns null for keys that the
 // sync layer does not own, and for paths that escape their channel root.
-export function resolvePruneEntry(manifestKey, { pruneChannels, packageRoot }) {
+export function resolvePruneEntry(manifestKey, { pruneChannels }) {
   let channel
   let relativePath
 
+  // Scaffold-only namespace for project-owned files. There is no package source
+  // to compare against and nothing here may ever be deleted.
+  if (manifestKey.startsWith('__project__/')) {
+    return null
+  }
+
   if (manifestKey.startsWith('__opencode__/')) {
     channel = pruneChannels.opencode
     relativePath = manifestKey.slice(channel.prefix.length)
@@ -289,22 +509,20 @@ export function resolvePruneEntry(manifestKey, { pruneChannels, packageRoot }) {
   } else {
     channel = pruneChannels.agents
     relativePath = manifestKey
-    if (excludedRelativePaths.has(relativePath)) {
-      return null
-    }
   }
 
   if (!relativePath) {
     return null
   }
 
-  const packagePaths = [resolve(channel.packageDir, relativePath)]
-  if (channel === pruneChannels.root && relativePath === 'opencode.json') {
-    // opencode.json is scaffolded from the example when the package does not ship
-    // it directly (auto-copy pass above). Either source keeps the file alive.
-    packagePaths.push(resolve(packageRoot, 'opencode.mcp.example.json'))
+  // Project-owned files survive every prune, even when the package no longer
+  // ships a same-named path. This is the single check for all four channels.
+  if (isProjectOwnedPath(relativePath)) {
+    return null
   }
 
+  const packagePaths = [resolve(channel.packageDir, relativePath)]
+
   const consumerPath = resolve(channel.consumerDir, relativePath)
   if (!isPathInside(channel.packageDir, packagePaths[0])) {
     return null
@@ -356,9 +574,11 @@ export function syncProject(context) {
 
   /* ──  Sync .agents/ directory ────────────────────────────────── */
 
+  // Project ownership outranks every flag: these paths are skipped before the
+  // --force branch below, so --force can never replace consumer-owned content.
   for (const sourceFile of sourceFiles) {
     const relativePath = relative(sourceAgentsDir, sourceFile)
-    if (excludedRelativePaths.has(relativePath)) {
+    if (isProjectOwnedPath(relativePath)) {
       continue
     }
 
@@ -396,7 +616,11 @@ export function syncProject(context) {
 
     for (const sourceFile of openCodeFiles) {
       const relativePath = relative(sourceOpenCodeDir, sourceFile)
-      if (openCodeExcluded.has(relativePath) || openCodeExcluded.has(relativePath.split('/')[0])) {
+      if (
+        isProjectOwnedPath(relativePath) ||
+        openCodeExcluded.has(relativePath) ||
+        openCodeExcluded.has(relativePath.split('/')[0])
+      ) {
         continue
       }
 
@@ -434,6 +658,10 @@ export function syncProject(context) {
   let scriptsSkipped = 0
 
   for (const scriptRelPath of scriptsToSync) {
+    if (isProjectOwnedPath(scriptRelPath)) {
+      continue
+    }
+
     const sourceFile = resolve(sourceScriptsDir, scriptRelPath)
     const targetFile = resolve(targetScriptsDir, scriptRelPath)
 
@@ -473,6 +701,12 @@ export function syncProject(context) {
   /* ──  Sync root files ────────────────────────────────────────── */
 
   for (const rootFile of rootFiles) {
+    // Defense in depth: projectOwnedPaths wins if a project-owned name is ever
+    // added to rootFiles. opencode.json is no longer in this allowlist at all.
+    if (isProjectOwnedPath(rootFile)) {
+      continue
+    }
+
     const sourceFile = resolve(packageRoot, rootFile)
     if (!existsSync(sourceFile)) {
       continue
@@ -542,11 +776,60 @@ export function syncProject(context) {
     scaffolded += 1
   }
 
+  /* ──  Scaffold project-owned files ───────────────────────────── */
+
+  // Create-if-absent only. The __project__ namespace is reporting metadata
+  // written when a file is first created by sync; pre-existing consumer files
+  // are intentionally absent, because there is no managed baseline to report.
+  // It is never resolved by the copy or prune passes and never drives an
+  // overwrite. Not refreshing it on later runs keeps a consumer-owned file from
+  // producing manifest churn on every install.
+  const targetPrettierIgnore = resolve(consumerRoot, '.prettierignore')
+  const prettierIgnoreExisted = existsSync(targetPrettierIgnore)
+
+  for (const [fileName, fileContent] of Object.entries(projectOwnedStubs)) {
+    const targetFile = resolve(consumerRoot, fileName)
+    const trackedKey = `__project__/${fileName}`
+    let didScaffold = false
+
+    if (!existsSync(targetFile)) {
+      ensureParentDirectory(targetFile)
+      if (isVerbose) console.error(`  … scaffolding: ${fileName}`)
+      writeFileSync(targetFile, fileContent, 'utf8')
+      scaffolded += 1
+      didScaffold = true
+    }
+
+    // Only hash what this run created, and only if it is a regular file: a
+    // directory or unreadable path at this location must not abort the run.
+    if (didScaffold && isRegularFile(targetFile)) {
+      manifest.files[trackedKey] = hashFile(targetFile)
+    }
+  }
+
+  // An existing .prettierignore is project-owned and is never edited. Tell the
+  // consumer when it leaves managed files exposed, once and deterministically.
+  if (prettierIgnoreExisted) {
+    try {
+      const missingPatterns = missingPrettierIgnorePatterns(
+        readFileSync(targetPrettierIgnore, 'utf8'),
+      )
+      if (missingPatterns.length > 0) {
+        console.warn(prettierIgnoreWarning)
+      }
+    } catch {
+      // A directory or unreadable path at .prettierignore is project-owned
+      // state we cannot inspect. Skip the advisory rather than abort the run.
+    }
+  }
+
   /* ──  Auto-copy opencode.mcp.example.json → opencode.json ────── */
 
+  // Existing consumer configs are never rewritten. The example carries the
+  // `instructions` entry that loads AGENTS.project.md for fresh consumers.
   const exampleMcpFile = resolve(packageRoot, 'opencode.mcp.example.json')
   const targetMcpFile = resolve(consumerRoot, 'opencode.json')
-  const mcpTrackedKey = '__root__/opencode.json'
+  const mcpTrackedKey = '__project__/opencode.json'
 
   if (existsSync(exampleMcpFile) && !existsSync(targetMcpFile)) {
     if (isVerbose) console.error('  … scaffolding: opencode.json from example')