mister-wolf 2.19.0 → 2.20.0

package/dist/adapters/render/opencode/opencode-renderer.js

@@ -4,8 +4,9 @@ import { basename, join, relative } from 'path';
 import { mkdir } from 'fs/promises';
 import { writeFileAtomic } from '../../fs/markdown-memory-store.js';
 import { OPENCODE_MANIFEST, substitute } from '../manifest.js';
-import { insertStamp, parseStamp } from '../stamp.js';
+import { insertStamp, parseStamp, renderStamp, stripStampLines } from '../stamp.js';
 import { loadSyncState, saveSyncState, sha256 } from '../sync-state.js';
+import { normalizeManaged, parseProtect } from '../../../domain/protect-key.js';
 import { wolfVersion } from '../templates-root.js';
 const NEUTRAL_DIRS = ['agents', 'skills', 'commands'];
 const LAYOUT = {
@@ -13,8 +14,47 @@ const LAYOUT = {
     skills: '.opencode/skills',
     commands: '.opencode/command',
 };
-/** Маркер онбординг-блока в AGENTS.md (спека §4.2). */
-const ONBOARDING_MARKER = '<!-- wolf:onboarding v2 -->';
+/** Детект онбординг-блока версионно-агностичен (§4.5): литерал `vN` в коде
+ *  запрещён, иначе после смены версии шаблона существующий блок не распознаётся
+ *  и init/append допишет второй. Версия формата — только в шаблоне (ADR-3). */
+const ONBOARDING_OPEN = /^<!-- wolf:onboarding v(\d+) -->$/;
+const ONBOARDING_CLOSE = /^<!-- \/wolf:onboarding -->$/;
+/** Блок между маркерами: null — блока нет, 'broken' — открывающий без закрывающего. */
+function findOnboardingBlock(content) {
+    let offset = 0;
+    let start = -1;
+    let end = -1;
+    let version = 0;
+    for (const line of content.split('\n')) {
+        const text = line.replace(/\r$/, '');
+        if (start === -1) {
+            const m = text.match(ONBOARDING_OPEN);
+            if (m) {
+                start = offset;
+                version = Number(m[1]);
+            }
+        }
+        else if (end === -1 && ONBOARDING_CLOSE.test(text)) {
+            end = offset + line.length;
+        }
+        offset += line.length + 1;
+    }
+    if (start === -1)
+        return null;
+    return end === -1 ? 'broken' : { version, start, end };
+}
+/** Блок шаблона: единственный источник версии формата и текста обновления. */
+function templateBlock(template) {
+    const block = findOnboardingBlock(template);
+    if (block === null || block === 'broken')
+        return null;
+    return { version: block.version, text: template.slice(block.start, block.end) };
+}
+const MUTATED_REASON = 'mutated after render — differs from recorded render and fresh render; left untouched';
+/** Легаси-строка свидетеля → запись (loadSyncState уже нормализует; защита для типов). */
+const asEntry = (v) => v === undefined ? undefined : typeof v === 'string' ? { hash: v, origin: 'render', base: '0.0.0' } : v;
+/** Значение ключа для дайджеста: `true` | `X.Y.Z` | raw вне грамматики. */
+const protectValue = (p) => p.value ?? p.raw ?? '';
 export class OpencodeBaseSetRenderer {
     baseTemplatesRoot;
     opts;
@@ -68,88 +108,136 @@ export class OpencodeBaseSetRenderer {
         const state = loadSyncState(baseDir);
         for (const f of this.templateFiles(baseDir)) {
             const rel = relative(baseDir, f.target);
-            if (existsSync(f.target)) {
-                // diff-ветка (§4.5): unstamped — чужое (wx); stamped — сравнение контента
-                const current = readFileSync(f.target, 'utf-8');
-                if (parseStamp(current) === null) {
+            const fresh = this.renderContent(f, opts?.bake, opts?.models);
+            const d = this.classify(rel, f.target, fresh, state);
+            switch (d.state) {
+                case 'missing':
+                    await this.writeFresh(f.target, fresh);
+                    this.record(state, rel, fresh);
+                    outcomes.push({ file: rel, action: 'created' });
+                    break;
+                case 'protected':
+                    outcomes.push({ file: rel, action: 'skipped', protected: true, protect: protectValue(d.protect) });
+                    break;
+                case 'unstamped':
+                    // diff-ветка (§4.5): unstamped — чужое (wx)
                     outcomes.push({ file: rel, action: 'skipped', reason: 'exists, unstamped (wx policy)' });
-                    continue;
-                }
-                const fresh = this.renderContent(f, opts?.bake, opts?.models);
-                if (fresh === current) {
-                    state.files[rel] = sha256(fresh);
+                    break;
+                case 'identical':
+                    this.record(state, rel, fresh);
                     outcomes.push({ file: rel, action: 'skipped', reason: 'content identical' });
-                }
-                else if (state.files[rel] !== undefined && sha256(current) !== state.files[rel]) {
+                    break;
+                case 'heal':
+                    await this.writeFresh(f.target, fresh);
+                    this.record(state, rel, fresh);
+                    outcomes.push({ file: rel, action: 'updated', reason: `stamp drift healed (base ${this.setVersion})` });
+                    break;
+                case 'mutated':
                     // K6 (спека 2.16 §4): локальная правка штампованного файла не перебивается
                     // re-init — тот же mutated-skip, что в syncBaseSet (T010); blind reseed запрещён
+                    outcomes.push({ file: rel, action: 'skipped', mutated: true, reason: MUTATED_REASON });
+                    break;
+                case 'kept':
                     outcomes.push({
                         file: rel,
                         action: 'skipped',
-                        mutated: true,
-                        reason: 'mutated after render — differs from recorded render and fresh render; left untouched',
+                        kept: true,
+                        reason: `locally accepted (keep) at ${d.entry.base}`,
                     });
-                }
-                else {
-                    await writeFileAtomic(f.target, fresh);
-                    state.files[rel] = sha256(fresh);
+                    break;
+                case 'rewrite':
+                    await this.writeFresh(f.target, fresh);
+                    this.record(state, rel, fresh);
                     outcomes.push({ file: rel, action: 'updated', reason: 'content differs (diff branch, §4.5)' });
-                }
-                continue;
+                    break;
             }
-            state.files[rel] = sha256(await this.writeRendered(f, opts?.bake, opts?.models));
-            outcomes.push({ file: rel, action: 'created' });
         }
         outcomes.push(...(await this.renderAgentsMd(baseDir, opts?.models, state)));
         saveSyncState(baseDir, state);
         return outcomes;
     }
-    async syncBaseSet(baseDir, models) {
+    async syncBaseSet(baseDir, models, opts) {
         const ctx = models ?? 'omit'; // легаси без routing-объекта — omit (§4.5)
+        const backup = opts?.takeMutated?.backup;
         const outcomes = [];
         const seen = new Set();
         const state = loadSyncState(baseDir);
         for (const f of this.templateFiles(baseDir)) {
             seen.add(f.target);
             const rel = relative(baseDir, f.target);
-            if (!existsSync(f.target)) {
-                state.files[rel] = sha256(await this.writeRendered(f, undefined, ctx));
-                outcomes.push({ file: rel, action: 'created' });
-                continue;
-            }
-            const current = readFileSync(f.target, 'utf-8');
-            if (parseStamp(current) === null) {
-                outcomes.push({
-                    file: rel,
-                    action: 'conflict',
-                    reason: 'unstamped in place of a template one — the owner decides: rename / delete / accept the current one',
-                });
-                continue;
-            }
             const fresh = this.renderContent(f, undefined, ctx);
-            if (fresh === current) {
-                state.files[rel] = sha256(fresh);
-                outcomes.push({ file: rel, action: 'skipped', reason: 'content identical (M2)' });
-                continue;
-            }
-            // T010 mutated-skip: контент отличается и от записанного рендера (свидетель) —
-            // это локальная правка, не сдвиг канона; файл не трогаем, хэш не меняем.
-            const recorded = state.files[rel];
-            if (recorded !== undefined && sha256(current) !== recorded) {
-                outcomes.push({
-                    file: rel,
-                    action: 'skipped',
-                    mutated: true,
-                    reason: 'mutated after render — differs from recorded render and fresh render; left untouched',
-                });
-                continue;
+            const d = this.classify(rel, f.target, fresh, state);
+            switch (d.state) {
+                case 'missing':
+                    await this.writeFresh(f.target, fresh);
+                    this.record(state, rel, fresh);
+                    outcomes.push({ file: rel, action: 'created' });
+                    break;
+                case 'protected':
+                    outcomes.push({
+                        file: rel,
+                        action: 'skipped',
+                        protected: true,
+                        protect: protectValue(d.protect),
+                        reason: d.protect.unrecognized
+                            ? 'held by protect (unrecognized value — treated as protected)'
+                            : 'held by protect',
+                    });
+                    break;
+                case 'unstamped':
+                    outcomes.push({
+                        file: rel,
+                        action: 'conflict',
+                        reason: 'unstamped in place of a template one — the owner decides: rename / delete / accept the current one',
+                    });
+                    break;
+                case 'identical':
+                    this.record(state, rel, fresh);
+                    outcomes.push({ file: rel, action: 'skipped', reason: 'content identical (M2)' });
+                    break;
+                case 'heal':
+                    await this.writeFresh(f.target, fresh);
+                    this.record(state, rel, fresh);
+                    outcomes.push({ file: rel, action: 'updated', reason: `stamp drift healed (base ${this.setVersion})` });
+                    break;
+                case 'mutated': {
+                    if (!backup) {
+                        outcomes.push({ file: rel, action: 'skipped', mutated: true, reason: MUTATED_REASON });
+                        break;
+                    }
+                    // Правило 6′ §4.3/§4.12: бэкап → эталон → свидетель (порядок обязателен, NFR-05)
+                    const backupPath = await backup(rel, d.current);
+                    await this.writeFresh(f.target, fresh);
+                    this.record(state, rel, fresh);
+                    outcomes.push({
+                        file: rel,
+                        action: 'updated',
+                        backup: backupPath,
+                        reason: 'take-on-mutated (--yes): local copy saved',
+                    });
+                    break;
+                }
+                case 'kept': {
+                    const base = d.entry.base;
+                    outcomes.push({
+                        file: rel,
+                        action: 'skipped',
+                        kept: true,
+                        reason: `locally accepted (keep) at ${base}${base !== this.setVersion ? `, base ${this.setVersion}` : ''}`,
+                    });
+                    break;
+                }
+                case 'rewrite': {
+                    // Правило 7: записи свидетеля нет — локальный контент сначала в бэкап (NFR-05).
+                    const backupPath = !d.entry && backup ? await backup(rel, d.current) : undefined;
+                    await this.writeFresh(f.target, fresh);
+                    this.record(state, rel, fresh);
+                    outcomes.push({ file: rel, action: 'updated', ...(backupPath ? { backup: backupPath } : {}) });
+                    break;
+                }
             }
-            await mkdir(join(f.target, '..'), { recursive: true });
-            await writeFileAtomic(f.target, fresh);
-            state.files[rel] = sha256(fresh);
-            outcomes.push({ file: rel, action: 'updated' });
         }
-        outcomes.push(...(await this.syncAgentsMd(baseDir, ctx, state)));
+        outcomes.push(...(await this.syncAgentsMd(baseDir, ctx, state, backup)));
         const orphaned = [];
         const scanRoots = [
             join(baseDir, '.opencode/agents'),
@@ -168,10 +256,76 @@ export class OpencodeBaseSetRenderer {
         saveSyncState(baseDir, state);
         return { outcomes, orphaned };
     }
+    /** Блочный режим AGENTS.md (§4.5): управляется только текст между маркерами;
+     *  контент выше и ниже — байт-в-байт. protect у AGENTS.md не поддерживается.
+     *  Штампованная цель с блоком (миграция 2.19.0 → 2.20.0, M-1) после замены
+     *  блока получает штамп текущей базы и свидетель; `state` передаёт только
+     *  init-ветка (блочный файл без штампа свидетеля не имеет). */
+    async syncAgentsBlock(target, current, template, state) {
+        const block = findOnboardingBlock(current);
+        if (block === null) {
+            return {
+                file: 'AGENTS.md',
+                action: 'skipped',
+                reason: 'no onboarding block — left untouched (wx policy)',
+            };
+        }
+        const tpl = templateBlock(template);
+        if (block === 'broken' || tpl === null) {
+            return {
+                file: 'AGENTS.md',
+                action: 'skipped',
+                reason: 'onboarding markers broken — file treated as foreign (wx policy)',
+            };
+        }
+        // [start,end) включает завершающий `\r` закрывающего маркера: блок наследует
+        // EOL маркера (а не шаблона) и подстановка кончается тем же `\r`, иначе после
+        // маркера остаётся LF (m-7).
+        const eol = current[block.end - 1] === '\r' ? '\r\n' : '\n';
+        const text = eol === '\r\n' ? `${tpl.text.replace(/\n/g, '\r\n')}\r` : tpl.text;
+        const replaced = `${current.slice(0, block.start)}${text}${current.slice(block.end)}`;
+        const updated = this.restampAgents(replaced);
+        if (updated === current) {
+            return { file: 'AGENTS.md', action: 'skipped', reason: 'content identical (onboarding block)' };
+        }
+        await this.writeFresh(target, updated);
+        if (state)
+            this.recordAgentsBase(state, updated, template);
+        const blockChanged = current.slice(block.start, block.end) !== text;
+        return {
+            file: 'AGENTS.md',
+            action: 'updated',
+            reason: blockChanged
+                ? `onboarding block ${block.version} → ${tpl.version}`
+                : `stamp drift healed (base ${this.setVersion})`,
+        };
+    }
+    /** Штампованная цель с блоком: штамп приводится к текущей базе **на своём
+     *  месте** (позицию задаёт `insertStamp` — после frontmatter, `---` остаётся
+     *  первой строкой). Без нового регекса штампа (§4.4): канонический текст
+     *  `renderStamp` заменяется строкой текущей базы; нестандартную запись штампа
+     *  не переписываем (файл честно останется `mutated`). */
+    restampAgents(content) {
+        const stamp = parseStamp(content);
+        if (stamp === null || stamp.set === this.setVersion)
+            return content;
+        const old = renderStamp(stamp, 'AGENTS.md');
+        if (!content.includes(old))
+            return content;
+        return content.replace(old, renderStamp({ base: 'AGENTS.md', set: this.setVersion }, 'AGENTS.md'));
+    }
+    /** Свидетель после обновления блока: только если файл совпал с эталоном
+     *  (EOL отличием не считается — проход приводит его правилом 7). Иначе
+     *  локальный текст вне блока остаётся решением `mutated` и не перезаписывается. */
+    recordAgentsBase(state, written, template) {
+        const fresh = insertStamp(template, { base: 'AGENTS.md', set: this.setVersion }, 'AGENTS.md');
+        if (written === fresh || written.replace(/\r\n/g, '\n') === fresh)
+            this.record(state, 'AGENTS.md', written);
+    }
     /** T10 (REQ-08): read-only инспекция целей base-set — предикат того, что
      *  сделает syncBaseSet, БЕЗ записей (ни writeFileAtomic, ни saveSyncState):
-     *  missing / foreign (unstamped, wx-политика) / identical / differs /
-     *  mutated (свидетель sync-state говорит о локальной правке). models по
+     *  missing / protected / foreign (unstamped, wx-политика) / identical (в т.ч.
+     *  штамп-дрейф: проходу нечего решать) / differs / mutated / kept. models по
      *  умолчанию 'omit' — паритет с syncBaseSet, чей исход и предсказываем. */
     async inspectBaseSet(baseDir, opts) {
         const ctx = opts?.models ?? 'omit'; // легаси без routing-объекта — omit (§4.5)
@@ -179,30 +333,93 @@ export class OpencodeBaseSetRenderer {
         const outcomes = [];
         for (const f of this.templateFiles(baseDir)) {
             const rel = relative(baseDir, f.target);
-            if (!existsSync(f.target)) {
-                outcomes.push({ file: rel, action: 'missing' });
-                continue;
-            }
-            const current = readFileSync(f.target, 'utf-8');
-            if (parseStamp(current) === null) {
-                outcomes.push({ file: rel, action: 'foreign' });
-                continue;
-            }
             const fresh = this.renderContent(f, opts?.bake, ctx);
-            if (fresh === current) {
-                outcomes.push({ file: rel, action: 'identical' });
-                continue;
+            const d = this.classify(rel, f.target, fresh, state);
+            switch (d.state) {
+                case 'missing':
+                    outcomes.push({ file: rel, action: 'missing' });
+                    break;
+                case 'protected':
+                    outcomes.push({
+                        file: rel,
+                        action: 'protected',
+                        protected: true,
+                        protect: protectValue(d.protect),
+                        detail: d.protect.unrecognized ? 'protect value is not recognized — treated as protected' : undefined,
+                    });
+                    break;
+                case 'unstamped':
+                    outcomes.push({ file: rel, action: 'foreign' });
+                    break;
+                case 'identical':
+                case 'heal':
+                    outcomes.push({ file: rel, action: 'identical' });
+                    break;
+                case 'mutated':
+                    outcomes.push({ file: rel, action: 'mutated' });
+                    break;
+                case 'kept':
+                    outcomes.push({ file: rel, action: 'kept', kept: true, keepBase: d.entry.base });
+                    break;
+                case 'rewrite':
+                    outcomes.push({ file: rel, action: 'differs' });
+                    break;
             }
-            outcomes.push({
-                file: rel,
-                action: state.files[rel] !== undefined && sha256(current) !== state.files[rel] ? 'mutated' : 'differs',
-            });
         }
         const agents = this.inspectAgentsMd(baseDir, ctx, state);
         if (agents)
             outcomes.push(agents);
         return outcomes;
     }
+    /** Реестр защит (§4.11, REQ-09): read-only обход каталогов base-set, включая
+     *  файлы вне карты. AGENTS.md в реестр не входит — protect у него не поддерживается. */
+    async listProtections(baseDir, base) {
+        const entries = [];
+        const roots = [
+            join(baseDir, '.opencode/agents'),
+            join(baseDir, '.opencode/skills'),
+            join(baseDir, '.opencode/command'),
+            join(baseDir, '.opencode/plugins'),
+        ];
+        for (const root of roots) {
+            if (!existsSync(root))
+                continue;
+            for (const abs of this.walkAbs(root)) {
+                const current = readFileSync(abs, 'utf-8');
+                const protect = parseProtect(current);
+                if (!protect.held)
+                    continue;
+                const rel = relative(baseDir, abs);
+                const fresh = this.renderFreshFile(baseDir, rel);
+                entries.push({
+                    project: baseDir,
+                    file: rel,
+                    value: protectValue(protect),
+                    recognized: !protect.unrecognized,
+                    stamp: parseStamp(current)?.set ?? null,
+                    base,
+                    behind: fresh === null ? null : normalizeManaged(current) !== fresh,
+                });
+            }
+        }
+        return entries.sort((a, b) => a.file.localeCompare(b.file));
+    }
+    /** Свежий рендер одного файла карты (эталон для `--show` и `behind`); null — вне карты. */
+    renderFreshFile(baseDir, rel, opts) {
+        // AGENTS.md — цель карты (agents_md), но не файл templateFiles: эталон для
+        // `--show`/`take` (design §4.8/§4.10) — штампованный whole-file рендер.
+        if (rel === 'AGENTS.md') {
+            const paths = this.agentsMdPaths(baseDir);
+            if (!paths)
+                return null;
+            return insertStamp(this.agentsMdContent(paths.tplPath, opts?.models ?? 'omit'), { base: 'AGENTS.md', set: this.setVersion }, 'AGENTS.md');
+        }
+        for (const f of this.templateFiles(baseDir)) {
+            if (relative(baseDir, f.target) === rel)
+                return this.renderContent(f, opts?.bake, opts?.models ?? 'omit');
+        }
+        return null;
+    }
     /** Read-only инспекция AGENTS.md (§4.2) — по фактическим веткам управления:
      *  штампованный цельный файл — зона syncAgentsMd (сверка всего файла со
      *  штампом, mutated по свидетелю); без штампа — маркер-блок append-ветки
@@ -216,21 +433,29 @@ export class OpencodeBaseSetRenderer {
             return { file: 'AGENTS.md', action: 'missing' };
         const current = readFileSync(paths.target, 'utf-8');
         const content = this.agentsMdContent(paths.tplPath, models);
-        const norm = (s) => (s.endsWith('\n') ? s : `${s}\n`);
         if (parseStamp(current) !== null) {
             const fresh = insertStamp(content, { base: 'AGENTS.md', set: this.setVersion }, 'AGENTS.md');
             if (fresh === current)
                 return { file: 'AGENTS.md', action: 'identical' };
-            const recorded = state.files['AGENTS.md'];
-            return {
-                file: 'AGENTS.md',
-                action: recorded !== undefined && sha256(current) !== recorded ? 'mutated' : 'differs',
-            };
+            const entry = asEntry(state.files['AGENTS.md']);
+            const hash = sha256(normalizeManaged(current));
+            if (entry && entry.hash !== hash)
+                return { file: 'AGENTS.md', action: 'mutated' };
+            if (entry && entry.origin === 'keep')
+                return { file: 'AGENTS.md', action: 'kept', kept: true, keepBase: entry.base };
+            return { file: 'AGENTS.md', action: 'differs' };
         }
-        const idx = current.indexOf(ONBOARDING_MARKER);
-        if (idx === -1)
+        const block = findOnboardingBlock(current);
+        if (block === null)
             return { file: 'AGENTS.md', action: 'foreign' };
-        return { file: 'AGENTS.md', action: norm(current.slice(idx)) === norm(content) ? 'identical' : 'differs' };
+        if (block === 'broken') {
+            return { file: 'AGENTS.md', action: 'foreign', detail: 'onboarding markers broken' };
+        }
+        const tpl = templateBlock(content);
+        if (tpl === null)
+            return { file: 'AGENTS.md', action: 'unknown' };
+        const same = block.version >= tpl.version && current.slice(block.start, block.end) === tpl.text;
+        return { file: 'AGENTS.md', action: same ? 'identical' : 'differs' };
     }
     /** AGENTS.md — цель в КОРНЕ проекта (§4.2); шаблона нет — тихо нет исхода. */
     agentsMdPaths(baseDir) {
@@ -251,56 +476,118 @@ export class OpencodeBaseSetRenderer {
         const content = this.agentsMdContent(paths.tplPath, models);
         if (!existsSync(paths.target)) {
             const written = insertStamp(content, { base: 'AGENTS.md', set: this.setVersion }, 'AGENTS.md');
-            await writeFileAtomic(paths.target, written);
-            state.files['AGENTS.md'] = sha256(written);
+            await this.writeFresh(paths.target, written);
+            this.record(state, 'AGENTS.md', written);
             return [{ file: 'AGENTS.md', action: 'created' }];
         }
         const current = readFileSync(paths.target, 'utf-8');
-        if (current.includes(ONBOARDING_MARKER)) {
-            return [{ file: 'AGENTS.md', action: 'skipped', reason: 'onboarding marker exists (§4.2)' }];
+        if (findOnboardingBlock(current) === 'broken') {
+            return [
+                {
+                    file: 'AGENTS.md',
+                    action: 'skipped',
+                    reason: 'onboarding markers broken — file treated as foreign (wx policy)',
+                },
+            ];
+        }
+        if (findOnboardingBlock(current) !== null) {
+            // блок уже есть: и init обновляет его по версии формата (§4.5), а не «вечно пропускает»
+            return [await this.syncAgentsBlock(paths.target, current, content, state)];
         }
         // marker-append: маркированный блок без штампа в конец; чужой контент не трогаем
         const block = content.endsWith('\n') ? content : `${content}\n`;
         const sep = current.endsWith('\n') ? (current.endsWith('\n\n') ? '' : '\n') : '\n\n';
-        await writeFileAtomic(paths.target, `${current}${sep}${block}`);
+        await this.writeFresh(paths.target, `${current}${sep}${block}`);
         return [{ file: 'AGENTS.md', action: 'appended', reason: 'marker-append (D3: foreign content untouched)' }];
     }
-    /** Sync-ветка AGENTS.md: только штампованный цельный файл; append-блок синку не принадлежит. */
-    async syncAgentsMd(baseDir, models, state) {
+    /** Sync-ветка AGENTS.md: только штампованный цельный файл; append-блок синку не принадлежит.
+     *  protect у AGENTS.md не поддерживается (§4.5); правила 6/6.5/7 §4.3 действуют,
+     *  включая take-on-mutated (6′) с бэкапом — механизм тот же, что у файлов карты (§4.12). */
+    async syncAgentsMd(baseDir, models, state, backup) {
         const paths = this.agentsMdPaths(baseDir);
         if (!paths)
             return [];
         const fresh = insertStamp(this.agentsMdContent(paths.tplPath, models), { base: 'AGENTS.md', set: this.setVersion }, 'AGENTS.md');
         if (!existsSync(paths.target)) {
-            await writeFileAtomic(paths.target, fresh);
-            state.files['AGENTS.md'] = sha256(fresh);
+            await this.writeFresh(paths.target, fresh);
+            this.record(state, 'AGENTS.md', fresh);
             return [{ file: 'AGENTS.md', action: 'created' }];
         }
         const current = readFileSync(paths.target, 'utf-8');
         if (parseStamp(current) === null) {
-            return [
-                { file: 'AGENTS.md', action: 'skipped', reason: 'no stamp (append block) — does not belong to sync (§4.2)' },
-            ];
+            // Блочный режим (§4.5): управляется только блок между маркерами; append-ветка —
+            // исключительно init (решение L0 2026-10-25), upgrade чужой файл не дописывает.
+            return [await this.syncAgentsBlock(paths.target, current, this.agentsMdContent(paths.tplPath, models))];
         }
         if (fresh === current) {
-            state.files['AGENTS.md'] = sha256(fresh);
+            this.record(state, 'AGENTS.md', fresh);
             return [{ file: 'AGENTS.md', action: 'skipped', reason: 'content identical (M2)' }];
         }
-        // T010 mutated-skip — то же правило, что и для файлов набора
-        const recorded = state.files['AGENTS.md'];
-        if (recorded !== undefined && sha256(current) !== recorded) {
+        const entry = asEntry(state.files['AGENTS.md']);
+        const hash = sha256(normalizeManaged(current));
+        if (entry && entry.hash !== hash) {
+            if (!backup)
+                return [{ file: 'AGENTS.md', action: 'skipped', mutated: true, reason: MUTATED_REASON }];
+            // Правило 6′ §4.3/§4.12: бэкап → эталон → свидетель (порядок обязателен, NFR-05)
+            const backupPath = await backup('AGENTS.md', current);
+            await this.writeFresh(paths.target, fresh);
+            this.record(state, 'AGENTS.md', fresh);
+            return [
+                {
+                    file: 'AGENTS.md',
+                    action: 'updated',
+                    backup: backupPath,
+                    reason: 'take-on-mutated (--yes): local copy saved',
+                },
+            ];
+        }
+        if (entry && entry.origin === 'keep') {
             return [
                 {
                     file: 'AGENTS.md',
                     action: 'skipped',
-                    mutated: true,
-                    reason: 'mutated after render — differs from recorded render and fresh render; left untouched',
+                    kept: true,
+                    reason: `locally accepted (keep) at ${entry.base}${entry.base !== this.setVersion ? `, base ${this.setVersion}` : ''}`,
                 },
             ];
         }
-        await writeFileAtomic(paths.target, fresh);
-        state.files['AGENTS.md'] = sha256(fresh);
-        return [{ file: 'AGENTS.md', action: 'updated' }];
+        // Правило 7: записи свидетеля нет — локальный контент сначала в бэкап (NFR-05).
+        const backupPath = !entry && backup ? await backup('AGENTS.md', current) : undefined;
+        await this.writeFresh(paths.target, fresh);
+        this.record(state, 'AGENTS.md', fresh);
+        return [{ file: 'AGENTS.md', action: 'updated', ...(backupPath ? { backup: backupPath } : {}) }];
+    }
+    /** Единый порядок решающих правил §4.3: missing → protect → unstamped →
+     *  identical → штамп-дрейф → mutated → kept → rewrite. Режимы (sync/render/
+     *  inspect) читают это решение и выполняют свою часть (запись или нет). */
+    classify(rel, target, fresh, state) {
+        if (!existsSync(target))
+            return { state: 'missing', fresh };
+        const current = readFileSync(target, 'utf-8');
+        const protect = parseProtect(current);
+        if (protect.held)
+            return { state: 'protected', fresh, current, protect };
+        if (parseStamp(current) === null)
+            return { state: 'unstamped', fresh, current };
+        const normalized = normalizeManaged(current);
+        if (normalized === fresh)
+            return { state: 'identical', fresh, current };
+        if (stripStampLines(normalized) === stripStampLines(fresh))
+            return { state: 'heal', fresh, current };
+        const entry = asEntry(state.files[rel]);
+        if (entry && sha256(normalized) !== entry.hash)
+            return { state: 'mutated', fresh, current, entry };
+        if (entry && entry.origin === 'keep')
+            return { state: 'kept', fresh, current, entry };
+        return { state: 'rewrite', fresh, current, entry };
+    }
+    /** Свидетель записи: хэш нормализованного контента + происхождение + база (§4.2). */
+    record(state, rel, written) {
+        state.files[rel] = { hash: sha256(normalizeManaged(written)), origin: 'render', base: this.setVersion };
+    }
+    async writeFresh(target, content) {
+        await mkdir(join(target, '..'), { recursive: true });
+        await writeFileAtomic(target, content);
     }
     renderContent(f, bake, models) {
         let rendered = substitute(readFileSync(f.tplPath, 'utf-8'), OPENCODE_MANIFEST, models);
@@ -310,12 +597,5 @@ export class OpencodeBaseSetRenderer {
         }
         return insertStamp(rendered, { base: f.baseName, set: this.setVersion }, f.baseName);
     }
-    /** Пишет рендер и возвращает записанный контент (T010: хэш для sync-state). */
-    async writeRendered(f, bake, models) {
-        await mkdir(join(f.target, '..'), { recursive: true });
-        const content = this.renderContent(f, bake, models);
-        await writeFileAtomic(f.target, content);
-        return content;
-    }
 }
 //# sourceMappingURL=opencode-renderer.js.map